Status-Q

Quote:

The only example of a wiki that worked is Wikipedia, and that’s not really a wiki in the true sense, because it is heavily edited by such a small number of people.

That’s Russell Keith-Magee, speaking on a podcast (so I may not have quoted him exactly). He was talking particularly in the context of software documentation, but I think, on consideration, that he’s right.

Don’t get me wrong, I love wikis, use them quite a bit, and shook Ward Cunningham‘s hand very enthusiastically when I met him a few years ago. But on the other hand, if one has been spoiled by the quality of documentation in projects such as Django, it makes one’s heart sink when exploring a new piece of software to discover that the documentation is ‘only a wiki’.

Wikis are great for their free-form, collaborative nature – remember, they came into existence long before Google docs and SubEthaEdit – but they also suffer from a few key problems:

• They can make you feel as if you’ve done something about documentation, so you don’t do the real work. “The crowd will fix it later”.
• The fact that you don’t need to think about the structure early on means they often need to be reorganised – making it hard for others to find things even if they’ve visited before, and harder to link to things reliably.
• It’s notoriously difficult to move content from a wiki into anything else, including another wiki package.
• It can be hard, with a software package, to know to which version the documentation applies.
• As with mind-maps, the free-form nature closely represents the mental model of the author. It’s good for personal notes and reference (Voodoopad is lovely, for example), but the difference between structured documentation and a wiki is the difference between a talk/lecture and a rambling conversation. The letter may be more fun, but does it achieve as much in the same amount of time?

None of this means, of course, that you can’t write good documentation with a wiki. It’s just very rarely done, and when it is done, it probably takes a lot of effort. Wikis are the whiteboard doodle, the back-of-the-envelope scribble: they can be useful within a small internal group of collaborators, but they’re not the thing you want to present to the world.

Actually, I think one of the best ways of doing documentation was the approach adopted by the PHP developers many, many years ago – you write proper docs but allow comments at the bottom of each page. Here’s an example. They did this long before the concept of comments-at-the-bottom-of-the-page was well established.

What do you think?