Creating Great Documentation

We’ve been struggling with ways to improve our documentation for quite a while, but we’re still finding that our documentation just isn’t good enough. The biggest frustration with the current tool is that you can’t link to a specific page on our web site so our support team has to tell people to go to the manual, click this then that then this other thing and scroll half way down the page. I think there was also a complaint that they look ugly.

On of the suggestions that has been floating around is to set up a wiki to use for our documentation. In an unusual moment of self-restraint I didn’t say “over my dead body”, but instead said “there’s some things you need to read”.

First and foremost, if you’re thinking about improving a product’s documentation, read Kathy Sierra’s How to get users to RTFM. Make sure your documentation covers each of the five types required:

• Reference Guide
• Tutorial
• Learning/Understanding
• Cookbook/Recipe
• Start Here

If 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 a look at Lars Trieloff’s comments and Dan Wood’s technique for packaging wiki content into something better for users. While it’s admirable that Dan got this working – it seems like an awful lot of effort for no benefit over using a decent documentation tool in the first place. I should also add another problem with using a wiki for documentation – it isn’t versioned with your product’s code so you lose the ability to go back in time and find the documentation for a specific version of your product. You can go back through the versions in the wiki, but you can’t tell which wiki version applied to which product version.

If you are dead keen on gathering user input on your documentation then consider something like PHP’s manual where users can add comments1. What you need to do on top of this though is to either highlight the really good user comments somehow, or actually capture that information into the manual itself. It tends to be pretty painful to filter through all the user comments looking for the bit of information that’s missing from the manual.

In terms of Ephox’s documentation I think we have a few problems:

• Mostly only reference. We have been working hard on building up tutorials so they’re coming along, but there’s no learning/understanding section, no cookbook/recipe and definitely no start here.
• Too much cruft floating around. In particular the descriptions of our product often feel like they’ve been automatically generated by a marketing droid instead of being written by an actual human. We need to rip these out and add in a Start Here section that is aimed at showing people how much more knowledge they’d capture and how much happier users would be if they had a high quality, well configured editor. The well configured is important, we want our users to customize our editor to fit their situation instead of making users work out what is appropriate to use and what isn’t.
• A little bit of JavaScript and a new style sheet should hopefully clean up the output of our current tool. If not, we may need to modify the HTML templates that are used. It looks like it shouldn’t be too difficult. We can also add post processing to inline frames to make linking easier and JavaScript free.

Something for us to work on anyway. Hopefully we can find a way to get our users up and running faster and doing better stuff with less frustrations.

1 – but only for the ability to add comments – the manual is reference only and tends to be too hard to find what you want↩