The Finer Points of Writing User Documentation
By Helen Casabona(The following article was originally published in the 1995 Society of Technical Communication conference proceedings.)
When I was in the user publications group at NeXT, we were handed a charter to create casual books with personality. We were also told to condense the user documentation for an entire operating system and several bundled applications into 300 pages. And of course we had the top priority of providing accurate, complete, and easy-to-use information. The keys to pulling this off? Task orientation, flat hierarchy, carefully crafted page design, illustrations, and a casual, intelligent tone. We also broke some "rules"!
Organization
Simple, task-based user's guides are all the rage these days—or at least they should be. When documenting a piece of software, you've got to pull out all the stops to make it easy for your readers to learn exactly what they want to know. This means dispelling a few myths. Namely, you don't have to organize your book around the user interface, you don't need multiple level headings, and you can and should make topics fit on one page or two facing pages. The result can be a book that looks and works great.
Document Tasks, Not the Interface
When you document software that people perform tasks with, focus on the tasks, not on parts of the interface. Instead of a topic "Using the Font Panel" that explains settings in a panel (panel is NeXT's term for dialog box), document what you do with the panel, as in "Setting a New Font."
| Don't make readers infer what to do from how things work. | Tell
them what to do and they will see how things work. |
 |
|
You may find that a window or panel requires several tasks—for example, "Setting a Font" and "Previewing a Font." Depending on how your document and the interface are organized, these various tasks might even go in different parts of the book. That's OK. Organize tasks to make sense to the reader first, and secondarily to match the interface.
Think Sequence, Not Hierarchy
Readers can get lost in second-, third-, and fourth-level headings—especially when the headings fall on different page spreads and aren't distinct visually. That's why in the NEXTSTEP User's Guide, we did away with such hierarchy. Instead, each chapter consists only of top-level tasks.
In many cases, you can eliminate subtopics simply by elevating them to the top. Instead of relating the topics hierarchically, consider the best order to present them in. If there are several ways to do the same thing, begin with the most common way and then follow with variations—for example, "Opening a Folder" and then "Opening a Folder by Typing." Ask yourself these questions: Is there a chronology, as in "Starting up the Edit Application," "Creating a New Document," and "Saving a Document"? Is there a progression from basic to advanced, as in "Looking Up Mail Addresses," "Creating a Mail Address Book," and "Creating Your Own Group Address"? Or is there just a list of separate but related tasks?
Fit Topics on One- or Two-Page Spreads
You can do readers an incredible service by fitting topics on either one page or two facing pages. Try even to have single-page topics on facing pages complement each other. For example, "Typing Text" might face "Selecting Text." Readers can then see the entire scope of a topic at a glance.
| Each
topic should occupy either one or two pages. |
Two-page topics should occupy the same split. |
|
|
| Don't make the reader turn pages within a topic. |
 |
If a task is too involved to fit on one or two pages, break it up into several tasks. Instead of tackling "Getting Faxes" all at once, document "Checking for Faxes," "Opening a Fax," "Changing How a Fax is Displayed," and so on.
If a task has a too many variations to fit on a page or spread, describe the vanilla case in one task and describe each option in subsequent tasks. For instance, the topic "Sending a Message" can describe sending a no-frills electronic mail message. "Attaching a File or Folder," "Recording and Inserting Sound in a Message," "Forwarding a Message," and so on, elaborate on how to dress the message up.
It takes effort to write to a page or spread, but that effort results in streamlined and well thought-out writing. You learn to think carefully about whether certain information is truly necessary—for instance, must you really point out that clicking a button highlights it? You also learn to cut extraneous language and to replace long descriptions with illustrations. Working in a strong page design with a good editor will do wonders for your writing.
Page Design
It's perhaps an unfortunate fact, but most people don't really want to read user documentation. Instead, they eventually have to. When this happens, they want to find an answer fast—not just the topic that contains the answer, but the answer within the topic. This is where a good page design comes into play.
Put Everything in Its Place
You can make specific types of information on the page visually distinct so readers can key in quickly on what they're looking for. In the NEXTSTEP User's Guide, how-to steps provide the bare bones "how do I do this," body text and illustrations provide context and details, cross-references are set apart in the lower margin where they don't interrupt the main discussion, and information that's not immediately part of a task is set apart in a sidebar.
Readers can quickly choose what they want to focus on. Also, the distilled information comes in shorter, more manageable chunks.
Make Each Element Work on Its Own
A segregated page design works well for all kinds of readers—whether they look first at steps, at body text, or at illustrations. Just make sure that each element makes sense when read on its own. How-to steps should provide just enough information for a reader who doesn't need context or details. The callouts and illustrations should make sense if they're all you read. And since cross-references are set apart from the text they refer to, they need context, too:
| Example | You
can also set font properties with the Bold or Italic command. See
"Standard Commands." If you don't know an address, you can look it up. See "Looking Up Mail Addresses" in Chapter14. |
Replace Words with Pictures
To document a graphical user interface you have to show pictures of what you're talking about. Obvious tactics are to illustrate a sequence of events in a task or to identify parts of the interface. But don't stop there. Use illustrations in place of wordy explanations. Look through your documentation for big chunks of text and ask yourself, Could I show this with an illustration? For example:
| Instead of | You can type a range of pages in the From and To fields. If you type a starting page number, the To field automatically changes to last and the file prints from your starting page to the end. If you type an ending page number, the From field automatically changes to first and the file prints from the beginning to your ending page. |
| Try this | You can type a range of pages: |
 |
These fields are filled in automatically if you type only one page number. |
Just Say It Once
It's tempting to repeat information in a callout that's also stated in a how-to step or body text. If a step says Click in the window to bring it forward, a callout pointing to an illustration of the window can say the same thing, right?
The fact is, in a page-oriented design you can't waste page real-estate by repeating information. If you must reiterate something, try to add another piece of information or perspective. If a how-to step says Click in the window to bring it forward, the callout can say Clicking in a window makes it the active window or When a window comes forward, its title bar becomes black.
Use Sidebars to Keep Tasks Streamlined
Even in a task-oriented document you have to explain concepts. You may also have tables of data or a lengthy list of options. To keep tasks streamlined, try putting information that isn't immediately part of a task in a sidebar or feature page. This information can include concepts, options, overviews, extended descriptions, tables, and so on.
| A visually distinct sidebar on the same page as a task provides information peripheral to that task. | A feature page can contain peripheral information that isn't subordinate to one task but relates to many. |
 |
|
Readers aren't interrupted with peripheral information while trying to perform a task. Instead, they can read it at their convenience. To help them know whether the sidebar or feature page contains information they need, use a descriptive heading rather than a label. Instead of "Fonts" try "What Is a Font?"
Style
Gone are the days of being told not to use the second person you. Also on the wane is our profession's obsession with the passive voice. That's a relief! But to really connect with readers, try relaxing your style even more.
Write Like You Speak
Write the way you would talk to a reader you know, like, and respect. Use contractions when natural. For example, Don't delete the file reads a lot more smoothly than Do not delete the file.
Go ahead and end a sentence or phrase with a preposition if that's what sounds most natural. For example, people read the folder you're copying from more easily than the folder from which you are copying. Also, avoid academic writing, even if it means breaking a grammatical tradition. For example, There's no ellipsis in its icon is more accessible to readers than the stilted No ellipsis is in its icon.
But First, Please Tell Me Why I Care
When you introduce a task topic, you can get your readers' attention and best make your point by focusing on what they can do with the software, not on what a command or window does. Tell readers first what they can do and why they'd want to do it. Then tell them how. For example,| Instead of | The Print command opens the Print panel. This panel has options for selecting a printer, a range of pages, and the number of copies to print. |
| Try this | When you're ready to print a file, you select a printer, the pages you want to print, and the number of copies. You make these choices with the Print panel. |
If you're introducing a concept, tell readers how the concept relates to them. Under the heading The File System:
| Instead of | The file system is divided into files and folders. Files contain information such as documents, and folders contain other files. |
| Try this | Your computer keeps information in files and folders. A file might be an article you write or an illustration. A folder can contain other files. The files and folders make up the computer's file system. |
Treat Readers As Equals
No matter how inexperienced readers may be with your topic, address them as intelligent adults. Don't talk down to them or be negative as you might to a child. For example, instead of You must type your user name exactly or else you won't be logged in, try If you make a mistake typing your user name, just try again.
Don't overuse the imperative. To much do this or do that can be unfriendly and condescending, especially when the reader has a choice. For example, instead of Press Return to log out or click Cancel if you change your mind, try You can press Return to log out, or if you change your mind, click Cancel.
Also, avoid using lets you or allows you to. The computer shouldn't let, allow, or enable people to do anything. Neither do any of its subparts, such as commands, menus, or panels. Instead, try you can do xyz.
Avoid Techy Words
When you're writing user documentation, there are several technical terms you can easily avoid. Even though these words may be common in computer literature, they aren't helpful to the general population. For example, for many of us it sounds funny to boot our computer or to be a user. Instead of booting the computer try turning on the computer or starting the computer. Instead of other users on the network try other people on the network.
Say More with Less
Don't overexplain things. People learn faster when they have less verbiage to wade through. Provide a concept and just enough information so the reader can figure out the rest.
For example, don't explain the result of an action when that result is obvious or irrelevant, such as that a button is highlighted when you click it or that the screen is blue when you first turn on the computer.
There's almost always a way to shorten something after you first write it. For example:
| Instead of | How the Scale button affects your printed pages depends on the application you're working in. |
| Try this | The Scale button works differently in different applications. |
Think On a Higher Level
You can try these ideas in your writing and hopefully see some good results. Even if you don't agree with everything I've said here, your take-home message should be to think on a level higher than just getting the facts and grammar right. Provide solutions for your readers and remember that whether they're consumers or programmers, they're people just like you. Give your writing extra thought, from the organization down to the use (or nonuse!) of each word. Your result can have all the right information and be short and simple. When your manager says What took you so long? I could have done this in half the time, you'll know you succeeded.
References
(1) Casabona, Helen, Kathi Vian, and Roy West.
NEXTSTEP User's Guide, NeXT Computer, Inc. Redwood City, CA. 1994.
(2) Casabona, Helen. Writer's Handbook for Style and Design, NeXT Computer, Inc. 1994.