Stop Using Wikis As Documentation
A lot of projects these days have taken to using a wiki as a way to get the community to write the documentation for them. This appears to work really well with a huge range of pages being created telling you how to do all kinds of stuff. Unfortunately, for anyone who actually needs to learn about the project, these pages are about as useful as tits on a charging bull.
There's a few problems, first and foremost there's no organization. Users don't know where to look for the information they want, it's just scattered around the wiki. Even when an attempt is made at organizing things, it's usually done pretty badly - group the how tos to gether, plonk a link to a getting started guide somewhere and maybe a link to one of the install guides. Rarely do you find documentation that guides the user from getting basic information about what the product does through a simple guide to installing and getting started then on to a feature tour with tutorials etc. In other words, the wiki doesn't guide the user on their learning journey through the product.
Since Kathy Sierra was kind enough to post a detailed article on how to create great user manuals, let's look at the broad sections she identifies as required in manuals:
The Reference Guide
Wiki's are awful at this. They're just not organized enough to be good reference sources. Reference requires really good formal structures - particularly an index. Wiki's are just to free flowing to create this kind of structure. The fact that a wide range of people are building up the documentation makes it even worse - nothing follows the same style so user's are constantly adapting to new page layouts, ways of grouping things etc.
The Tutorial
Wiki's are actually quite good at this. The most common thing you come across on a wiki is the good old How-To guide. The only problem is that most of them are written after the fact. Someone has a hard time doing something so when they get it working they write down what they remember doing on the wiki. This leads to a lot of cliffs where people following the tutorial are missing a crucial step. It also leads to a lot of "it works on my machine" experiences. Just because it solved your problem doesn't mean what you did was right.
Learning/Understanding
I'm yet to see anything that comes even vaguely close to this on a product's wiki. There's a lot of pages that contain the word understanding, but they always seem to devolve into a How-To guide again.
Cookbook/Recipe
Wiki's are pretty good at this, though they are usually grouped in with the Tutorials under "How-To guides". Some wikis still struggle with this because noone pulls together the related tutorials or all the How-Tos are too specific.
Start Here
Every wiki tries this, most of them fail. As Kathy points out:
The problem with many Start Here guides is that they are about configuration and set-up and very little else. There's a Grand Canyon between the Start Here and… the rest of the manual.
Another point of Kathy's that rings true to me, since this complaint is inspired by my trying to get Ruby on Rails working:
Of course we've all seen Start Here guides that were total bait-and-switch–they do indeed look as if they were produced by an inspired and caring design department, but then the REAL manual looks like it was done by someone who really, really doesn't like you.
Go on, compare the getting started to the actual manual.
September 2nd, 2006 at 7:37 pm
I couldn’t agree more. I have seen two large adequately documented projects start to use wikis. They both have much more documentation now, but you can never find what you are looking for, when you do find it you are never sure if it is still relevant (you can delete from a wiki….just no one ever does). I shudder every time i point a newbie at the wiki because it’s lack of structure prevents and kind of cogent description/picture from emerging. Wikis are great for getting content down as a sort of notes sheet, they need to be backed by a proper structured web site though. If you are going to do just one ditch the wiki and go for a proper documentation site. The best compromise i have see is the php and mysql documentation, well structured but with user content in the comments.
September 3rd, 2006 at 8:15 am
It sounds like what’s needed is a way to move documentation that was created on the wiki into more formal documentation - cleaning it up along the way. That way content can be created on the wiki by the community and then a smaller group of people who care about the documentation can extract the important parts of that knowledge into the formal manual. They can then identify the missing points and either write it themselves or put a request on the wiki for the appropriate type of content.
This could probably be done with wikis today, but I suspect improved tools support would make it much more likely to happen. Such a tool would combine a wiki with a document management system - anyone can edit the wiki and the document management side is more restricted and can pull in content from the wiki.
December 18th, 2006 at 12:12 pm
[...] Interesting post by Adrian Sutton, “Stop Using Wikis As Documentation” where Sutton points out some of the problems endemic to using wikis as a substitute for real documentation: There’s a few problems, first and foremost there’s no organization. Users don’t know where to look for the information they want, it’s just scattered around the wiki. Even when an attempt is made at organizing things, it’s usually done pretty badly - group the how tos to gether, plonk a link to a getting started guide somewhere and maybe a link to one of the install guides. Rarely do you find documentation that guides the user from getting basic information about what the product does through a simple guide to installing and getting started then on to a feature tour with tutorials etc. In other words, the wiki doesn’t guide the user on their learning journey through the product. [...]
February 6th, 2007 at 7:47 am
[...] you're thinking of using a wiki, see my earlier rant on how wiki's don't tend towards covering all those sections. You should probably also take [...]
May 26th, 2007 at 9:10 am
[...] Oh and did I mention that wiki's are a horrible way to write documentation? [...]