Editing, Writing, and Translation

Home Services Books Articles Resources Fiction Contact me Français

You are here: Articles --> 2006 --> A recipe for designing usable documentation
Vous êtes ici : Essais --> 2006 --> A recipe for designing usable documentation

A recipe for designing usable documentation

By Geoff Hart

Previously published as: Hart, G. 2006. Recipe for designing usable documentation. Usability Interface 12(1).

The most interesting discussions arise in the techwr-l discussion group ( One topic of conversation was how to define "user-friendly documentation". Opinions varied, as you might expect from such a wonderfully opinionated group, but the process of thinking about the discussion helped me define my own very subjective list of criteria. I make no claims that this list is broadly representative, but the range of positive feedback I received from proposing it strongly suggests that I touched on some sore spots and covered many of the key points that others consider important.

I summarized my opinions as follows: Usable documentation accommodates the way I think. This means that, among other things:

It thinks the way I do

Documentation that works well for me is organized in such a way that it matches my understanding of how the software works, or provides enough context for me to create that understanding where I formerly lacked it. The result is that I can find information quickly because I know what path I should follow through the hierarchy, or can quickly learn what path I should be following. Thus, I rarely find myself uncertain about whether I'm following the wrong path to a dead end many pages or links deep in a mysterious structure. That structure doesn't in any way have to be linear—it just has to be sufficiently obvious that I can see it immediately, or can discover it, understand it, and use it.

It matches the product

It should go without saying that the documentation must match the product closely, so that as soon as I see part of the interface, I immediately know what to look up in the documentation. Yet much documentation fails this simple test. Here are a few things that are generally lacking:

Short and sweet—yet still complete

Good documentation is concise—which means that it provides information economically, not that it's as short as you can make it without making it incomprehensible. It emphatically does not mean that the writing is terse and telegraphic or that it omits useful information in the interest of appearing short. One excellent but underused tool is the table. Using clear column headings eliminates the need to repeat that heading for each chunk of information, and appropriate subheadings within the body of the table facilitate skimming. You don't have to be an Information Mapping® (IM) disciple to use this approach, since tables have been in the public domain just about forever, but if you've never thought about the approach, IM can teach you a powerful and rigorous approach to applying tables.

To ensure that the documentation will be concise without sacrificing completeness, you must understand your audience well enough to know what their needs are: What do they hope to accomplish, and how do they hope to accomplish it? The documentation must be written with a clear understanding of all the things I need to accomplish with the product, including some of the following often-neglected aspects:

The idea of proposing online resources is particularly interesting in these days of the virtual community. The vast networks of people in online communities such as techwr-l have repeatedly proven their ability to solve just about any solvable problem, and there are similar Internet communities for just about any product or interest—some of them may even be hosted or provided by your employer. Spend some time finding these communities, and introduce them to the audience for your documentation. This does not relieve you of the burden to produce effective documentation, but it does greatly expand what you can accomplish with limited time and resources.

It thinks visually

Graphics should clearly be used to communicate any concept that proves the old maxim that "a picture is worth 1000 words", not simply to add color to the screen or page. If you find that you need to use more than a few words to describe something visual, that's a clue you should be describing it visually instead. For example, never force me to memorize which of your cryptic icons represents the "bowdlerize" tool; instead, show me the icon. I'll find the information I'm seeking much more quickly if I don't have to mentally translate between the text and the image before I can even begin looking.

The visual hierarchy of the page or screen must also use white space intelligently, in a way that supports hierarchical organization of the information. For example, brief instructions for experts should be clearly separated from detailed instructions for amateurs so that both are instantly available, depending on my needs at a given time. At the same time, the two must not be so densely intermingled that it's hard to separate them. This can be accomplished by an introductory overview of the main steps (to provide necessary context for the reader or remind an old pro about everything they need to remember) followed by detailed steps (for anyone who needs the details). You can sometimes do this by appropriate use of headings: provide the high-level information (the overall task for each step) as headings, and provide the details under the headings. For example:

Step 1. Do X:

[details of step 1]

Step 2. Do Y:

[details of step 2]

Step 3. Do Z:

[details of step 3]

Readers who just need a reminder of the three steps can read the headings and ignore the details, but those who need both forms of information have both forms available.

It's well indexed

Let's be blunt about this: indexing is a skill, and you won't ever get good at it if you don't study the theory, then practice applying that theory until you develop a reasonable level of skill. Unfortunately, developing even a rudimentary index takes time, and indexes require usability testing, even if that testing is nothing more than a good editorial review. If you can't meet these conditions, hire an indexer. They'll do the job faster, better, and less expensively than you could. If you can meet these conditions, budget time to create an index.

Here are some less-obvious things that amateurs tend to forget about indexing:

It doesn't forget unique needs

Of course, one person's meat is another person's vegan nightmare. All these suggestions will help make documentation better for most people, but still won't meet unique needs or provide the perfect solution for everyone. As always, you'll need to understand your audience's characteristics and needs to successfully determine what will make the documentation work for them. That understanding is what lets you strive to make the documentation usable.

©2004–2018 Geoffrey Hart. All rights reserved