In the beginning was the manual. There had to be – there was no online help, or even much assistance embedded in software. You had to, as IT used to say, RTFM (read the <censored> manual) to find out how to perform functions or troubleshoot errors.
Now, alas, there are very few FMs to R. And the documentation that does exist within software often just regurgitates the menus. Users have to resort to Internet searches yielding hundreds or thousands of probably irrelevant links, or online forums where the blind, aka fellow users, often lead the blind, and the quality of the advice can be dubious.
How did we get into this woeful state?
It all started with the graphical user interface (GUI). Vendors told us that it was intuitive, so we didn’t need documentation. They didn’t say, of course, that it also saved them a bundle, since they could dispense with the authoring and printing of docs, and did not have to incur the extra expense in packaging and shipping the heavy manuals. A CD or DVD in a box weighs almost nothing – but even when floppy disks were involved, the savings from dispensing with manuals were substantial.
Of course, what’s intuitive to one person is a complete puzzle to another. And contrary to the sometimes deluded beliefs of vendors, things still go wrong with software that has an “intuitive” interface – things that can’t be solved with a simple point and click. That’s where we see the value of proper documentation.
However, creating good documentation appears to be a dying art. Even when there is some sort of manual, today it’s usually a few sad pages that simply reproduce the application’s menus. There are no instructions on how to recover from problems, or how to do anything that isn’t covered by your basic point and click. For that, you have to rely on trial and error, or go hunting online.
But even online help is pretty useless. I have yet to get a reasonable single answer to a question, but instead receive long lists of usually irrelevant links to fish through. This is not helpful!
If you get the sense that it’s not easy to write good documentation, you’re right. Not only does the author have to understand every facet of the product (or have access to people who do), he or she needs the skill to explain how to do things in terms clear enough for the novice and deep enough for the expert user. Plus, a really good manual explains what error messages mean, and how to fix problems. That takes extensive use of the product and a delight in breaking things. Think of it as debugging on steroids.
It also requires co-operation from the designers and developers. They know how the application is supposed to work, and (theoretically at least) how to recover from errors.
Their goal, of course, is to produce error-free code, but we all know there’s no such thing. That means that developers have to include error traps so the inevitable glitches don’t make too big of a mess. And they also need to document those error messages, which are often obscure numeric strings, and pass that information on to the manual authors. It would be preferable to have understandable error messages, but that seems to be beyond most developers, possibly because they hope that no-one will ever see them (another pet peeve is the inevitable “OK” button we have to click to dismiss said messages. Guys, it is not OK! But that has nothing to do with the docs.).
Writing user manuals, although not the easiest job in the world, is well worth the effort. A bad manual can make people think that the product is bad, and a good manual can improve the user’s experience.
There are plenty of resources available to help with the task. Here are a few tips from the experts to help you make your help actually helpful.
- Know your audience. How technical are the users? What do they expect from the manual or help text? If possible, observe people who aren’t involved with the product as they actually use it – you’d be surprised how much you can learn about what needs explaining from watching someone who doesn’t know the product.
- Use active voice – tell people “click the button,” rather than “the button should be clicked.” And give them an instruction first, rather than tell them what result to expect at the beginning. For example, don’t say “The screen will turn blue after you do x,” just say “Do x. The screen will then turn blue.” Then tell them what to do, or provide a link to further information on what to do, if the expected result doesn’t occur.
- Numbered lists of instructions work better than long paragraphs of text. Lists are less intimidating, and the reader is more likely to follow them.
- Keep instructions concise. If you want to provide background information that isn’t relevant to the immediate task, link to it so the more casual user doesn’t have to wade through it.
- Keep vocabulary consistent. This isn’t a novel where you want to provide variety; using different words for the same thing will just confuse users.
- Include a section on troubleshooting. Things do go wrong, and the best way to lose your users is to leave them hanging in a problem state.
- If you’re creating online or in-application help, don’t just echo the menus (To open a document, click Open). It wastes everyone’s time.
- Proofread! Typos are confusing and project an unprofessional image. The product loses credibility.
- Once the documentation is complete, test it. Have people who don’t know the product go through the instructions and follow them precisely. That will bring ambiguity or errors into view before it wreaks havoc with the user population at large, and it may even reveal a software bug or two that the developers can address before release.
However, the task isn’t done when you think the docs are complete. The help desk can be your friend – check with them to see what questions and problems are coming in, and address them in documentation updates. It’ll make their job easier, and users happier. And that’s what helpful help is all about.
For more on best practices in help documentation, see:
Susan Bodnick, from Online-Learning.com was one source.
WikiHow provides a nice illustrated guide.
Psychologist Philip Hodgson at UserFocus was another reference.
