–Geoff-Hart.com: 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). http://www.stcsig.org/usability/newsletter/0605-usabledocumentation.html

The most interesting discussions arise in the techwr-l discussion group (www.techwr-l.com). 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:

For textual things, I want a way to find those things quickly. As I'll note later in this article, this means creating at least a minimal index.
For purely visual things, I want visual assistance: a visual "glossary" that shows every toolbar and icon in the software, complete with its name so I'll know where to look in the index. The only place I recall seeing this approach was in the manual for the AmiPro word processor, many years ago, and it was a tremendous aid.
For tangible things, such as hardware, I want an initial photographic overview of the product, with all the key components labeled clearly so I'll know how you refer to them in the documentation. An index entry for each of these labels is mandatory, but why send me to the index when you could simply include page references (or hyperlinks in an image map) directly in the image? My Nikon camera manual includes this kind of aid, and it's often more useful than the table of contents or index.
The instructions and explanations use the same language as the software, but provide synonyms where it's likely that I may be using a different "industry standard" jargon than the software uses. I still recall with considerable frustration trying to figure out how to type French accents in an early version of WordPerfect—none of the half dozen standard synonyms for WordPerfect's chosen keywords ("overstrike mode", if I recall) were anywhere to be found.

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:

How can I work around the product's known flaws? With a little thought, it's not hard to come up with a way to present an effective solution to reach a goal without ever explicitly stating that this solution wouldn't be necessary if the product were properly designed.
When should I use one alternative (or function or tool) instead of another? If there are (as in most Adobe software) two cursors, please make it clear why I should use one instead of the other—and when I can use either.
Where can I turn for additional help? For example, if I'm using Web-authoring software, I want a printed URL or hyperlink that takes me to the W3C tag references page and accessibility guidelines so I can look up this information quickly. Why waste your time including this information in your documentation when an authoritative group has already done all the hard work for you? Instead, spend your time documenting the things that only you can document! Similarly, if I'm using desktop publishing software, I want you to cite good books on typography, page design, and prepress work.

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:

The index should use synonyms. If you don't know what those synonyms should be, find an Internet community that uses the product and investigate the words they're using. (If they're not using them, ask!) You'll have your synonyms within a few hours.
The index should include every dialog box name so I can look up that name in the manual. If your icons and buttons and other visual widgets have tool tip names that pop up when the cursor hovers over them, index those words too. It's not helpful if your tool tip tells me I'm about to click on the "bowdlerize" tool, and that tool isn't listed under that name in the index.
If you're creating online docs, don't force me to rely on a primitive search function or a random walk through the table of contents to find what I'm seeking. Unlike printed pages, additional pages on the screen are free, so give me as many tables of contents as would prove useful; for example, provide one based on reference material and one based on tasks. If appropriate or useful, provide multiple indexes; for example, include a separate visual index for graphics, or offer ways to collapse a single comprehensive index into something more easily searchable (e.g., an author index for a collection of articles, with the author names separate from the topic keywords).
If you provide a search function, don't settle for one that's overly literal. Many current search tools are next to useless because they don't understand stemming (e.g., for the concept of writing, typing the "writing" keyword would also find "written", "to write", "wrote", etc.), "sounds like" searches (for those times when I only know how the jargon is pronounced but not spelled), synonyms (for those times when I don't know what words you chose to describe a product), or "related concepts" (e.g., if I'm searching for foreign-language characters, the search should also turn up links to Unicode fonts).

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.