Let me start off by saying that some people find these effective and so that's fine - to each his own. But frankly I really dislike Wikis especially in the way they are used as a central place for developers on the same team to document things related to their application.
From a technical point Wikis are great - a place where everyone and anyone can make updates and Wikipedia is wonderful (but there are good moderators in place - at least most of the time).
The problem is when the average developer gets a hold of it - and there's no real moderation - it becomes a Joycean stream of consciousness piece that, while it makes sense to the writer, isn't worth much to the guy or gal reading it and trying to get some stuff done.
The key, I guess, is structure - think about the kinds of papers etc. you would write in school or college for assignments - structure is key - a rambling set of paragraphs might work well in English Lit class but for us Tech geeks . . . . . . ouch! Think about recipes for cooking - a step-by-step guide with structure is a lot easier to follow than a big hunk of text.
Another issue is the dissolution of authorship - what's that? Well imagine a case where I read something on the Wiki that's confusing. So now I need to contact the author to find out what they meant by that - but who do I call/email?
So here are some guidelines for what helps me navigate a Wiki or what makes a Wiki good.
1) Use Headings
Delineate sections with headings and sub-headings e.g.
A) How to Install
B) How to run a quick scenario
C) How to create your own scenario
D) Troubleshooting guide
E) FAQ
2) Use Hyperlinks only to link away from your site
Such as for document repositories, good online articles etc. - not for links within the site as they start to diminish any "structure" to the Wiki.
3) Use breadcrumbs
They help people know where they are - for one reason or another people tend to think in structured and ordered ways and have cognitive limits to how much stuff they can keep in memory (where was I three clicks ago?)
4) Use bullets
They tend to help you reduce the amount of text you are writing and just focus on getting simple points across. Long paragraphs are arduous to read for those of us fighting the fight against information overload.
5) Iterate and improve
Try not to cram too much on one page - refactor! :-)
Remove redundant information.
6) Use Pictures
They provide less opportunity for confusion and communicate a lot with relatively little effort.
7) Follow the leader
If in doubt look at Wikipedia for ideas - especially they have quite a bit of usage of
- Good headings
- Good mix of bullets and plain old text paragraphs.
Check out Wikipedia's Style Guide
8) Enforcement
Small group of moderators with sense of 'ownership'. Someone usually has to enforce the structure.
9) Newbie test
If the newbie can't navigate around with ease you've got a problem to fix.
So getting back to why I don't like Wikis (at least insofar as their usage for communicating across development teams) -they don't provide easy ways to give structure to information that more often than not, at least in the world of software, needs structure.
Software is such a complex and abstract thing at times we need help in minimizing the cognitive overload inherent in the abstract concepts therein.
And then again maybe it's just me :-) Or maybe not . . .
"It seems to me that wikis are designed for people who don't really care whether their informtion[sic] is organized or accessible."
http://mamamusings.net/archives/2003/08/24/why_i_still_hate_wikis.php
"Wikis are the easiest way to create awful documentation"
http://www.alittlemadness.com/?p=5
" I realized why I hate editing wikis so much: for the same reason that no one speaks Esperanto."
http://www.snout.org/hotsheet/2005/12/i-hate-wikis.html
"Wikis dissolve authorship"
http://www.cjung.info/wordpress/?p=96
And now this one is really funny http://www.reddnet.net/Scribbles/682.aspx
Especially their response to the common refrain "Did you check the Wiki?".
6 comments:
So, if wikis aren't good for writing docs for your development team, why are you posting guidelines for their use?
Wikis aren't going away any time soon - if anything, adoption is increasing and if I can somehow do something to alleviate the pain . . . . .
:-)
-Frank
What's the alternative? Please don't say word processor docs. At least wiki pages have a prayer of being kept up to date, but once something is put in ms word, it's hard to change, hard to keep everyone on the correct version, and if it's a design doc, it's pretty close to written in stone (because of the first two things). Nothing I love more than asking for info and being thrown the design doc that hasn't been updated in 5 years.
Don't use links to go to pages within your wiki? Why don't you just upload word docs to a file repository then?
I put in links all the time so that people don't have to go search for the other documentation that this adds to. In fact I think that's the second best thing about a wiki (the best being that everyone can edit it with a simple syntax).
To anonymous,
No I agree word processor docs aren't the solution - the key question here is how do you maintain consistency of a single "text" written by multiple authors?
But there's also nothing to stop a Wiki being out-of-date either.
In the end I think it all comes down to ownership - whether it's word processing docs, Wikis or whatever.
Or until someone comes out with the killer app.
-Frank
I wonder why you guys have missed TWiki.
Post a Comment