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.