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
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
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."
"Wikis are the easiest way to create awful documentation"
" I realized why I hate editing wikis so much: for the same reason that no one speaks Esperanto."
"Wikis dissolve authorship"
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?".