The document discusses how to design user manuals that effectively answer the questions users typically have. It identifies four main questions users seek to answer: 1) Why should I care? (about basic program theory and usefulness), 2) What is it? (simple descriptions of interface elements), 3) How do I do it? (step-by-step instructions for tasks), and 4) Why did it do that? (explanations for unexpected program behaviors). The author recommends addressing the first two questions in online help and the latter two in paper manuals, as users prefer short answers online and longer procedural information in print.

1. Manual Labour Symposia Page 1 of 5
Symposia•Document to the Question
Why Do People Read Manuals?
Most software is run by confused users acting on incorrect and incomplete information, doing things the
designer never expected.
–Paul Heckel
If you watch people use software (or anything, but my primary experience is with software), often the first
thing you notice is that everyone has a different random approach to learning and using each program
feature. Given this individuality, how can we ever hope to create user manuals that more than one person
can use?
The best way I've found is to observe people using the product, or performing the tasks the software is
intended to replace or facilitate. The more you watch them the more you'll see a pattern emerge that
enables you to group information usefully. You may also notice the only constant I've been able to
discover: people turn to the online help or paper manual only when they have a specific question, usually
one that they cannot answer by experimentation.
An excellent paper in The Art of Human-Computer Interface Design by Brenda Laurel addressed this issue
in terms of online help. "Building User-Centered On-line Help" by Abigail Sellon and Anne Nicol discussed
some of the reasons why users don't like to use online help. They discovered two key points (p. 145):
The user's idea of the problem is often very different than the help or program designer's
The online help topics were usually designed to match the designer's conception, not the user's.
They used these points to group user questions into five categories and suggest that different help be
designed for each of the groups.
After reading the article, I decided to broaden the authors' ideas to include the entire user guide* set: paper
and online documentation both. I've noticed that people seek online help to answer some kinds of
questions, and turn to paper manuals to answer others.
What Are the Four User Questions?
Working from Sellon & Nicols' categories, I developed four specific questions that seem to include most of
the kinds of information users seek.
Why Should I Care?
This question involves basic program theory. In today's business world, software is frequently imposed
http://www.manuallabour.com/Question.htm 5/8/2007

2. Manual Labour Symposia Page 2 of 5
from above, to solve problems that management perceives. The people using the software directly may
not be consulted--they may just be handed the program and manual and informed that they will now use it.
In this situation, they ask "Why should I care?" or "What's in it for me?" Even if the user purchased or
requested the software directly, her or she may only have a marketing-brochure's idea of why the software
is useful. Specific reasons for using of specific features still require explanation.
Overviews, summaries, and theoretical background information answer this kind of question. For example,
you're writing a document describing SQL queries. Information answering "Why do I care" questions could
include
a brief overview of the process of creating a query and the kinds of results the user can expect
background on the way tables behave in a relational structure
theoretical information on the types of table joins
a business case in which data gleaned from a well-constructed query saved time and money
The idea is that users want to know why they need to use a program feature. Occasionally, they'll also
want to know why they need to use that feature in the specific way recommended by the manual (or
dictated by the software design).
What Is It?
This question involves simple description. No matter how "intuitive" the designer, or even most users, think
a product is, there are always users who need more information on its components.
Information answering "What is it?" include
descriptions of the information or choices required by elements of a dialog box or menu
glossary definitions of terms used in other descriptions
"bubble" help or graphic call-outs describing icons or toolbar buttons
Most users wont push a button or select a menu option, or change program preference defaults until they
know what the item is or controls.
How Do I Do It?
This question creates a procedure. Again, no matter how carefully the workflow is designed, there are
some people to whom it will not be obvious. If the program is a general use program (like a word processor
or spreadsheet), this likelihood increases. (Do you know any two writers who approach creating a
document in exactly the same way?)
Information answering "How do I do it?" includes
Step-by-step instructions
Notes, warnings, cautionary statements
Until users are comfortable with the program procedures, they're not going to like using it. A good example
of this is the new version of Corel Ventura--most of the dissatisfied users I hear talking about it cite the
new interface and procedures as a source of their unhappiness.
Why Did It Do That?
http://www.manuallabour.com/Question.htm 5/8/2007

3. Manual Labour Symposia Page 3 of 5
Any object, whether it's software or a telephone or a microwave oven, occasionally displays unexpected
behavior. The unexpected is disturbing to users no matter what level of sophistication they posses. If a
behavior is weird, but normal, they need to be reassured. If a behavior is the result of an error (either their
own or a bu--I mean, undocumented feature), the need to be reassured and told how to fix it, if possible.
Information answering "Why did it do that?" includes
Helpful error message text
Notes on procedures anticipating and explaining what users may find unexpected
Instructions for correcting the problem (if it is a problem)
As with describing procedures (How do I do it?), user comfort level is a serious issue. Many naive users
are convinced they have "broken" something when they receive an error message, or if a process takes
longer than they expect. They need to hear that everything's all right, or be given instructions on how to
make it so.
How Do I Decide Where They'll Look?
Once I devised the questions, I knew I needed a method for determining what information went where. As I
mentioned earlier, my primary experience is in writing software documentation, which means that my user
guide set usually includes both paper manuals and online help.
While there are many advocates for single-sourcing documentation (using the same set of text for both
paper and online information), I have found that users look for entirely different kinds of help from each
medium. They are often disappointed and even aggravated by finding the same information in both places.
There seems to be a feeling of "Well the [first medium checked] didn't have what I wanted; maybe the
[other medium] will."
Again, by observing users informally (including myself) I noticed that they look for the answers to two of
the questions in one medium and the other two in the other.
Online
Users tend to press F1 (or the system equivalent) to find the answers to "What is it" and "Why did it do
that?" and occasionally "How do I do it?"
What is It?
Here they're looking for quick answers, brief descriptions, or reminders of what's required. They're usually
using the program when these questions arise, so turning to the online help is natural, and does not
interrupt the workflow substantially. Because the answers to this question are generally short, they fit
easily onto one screen's worth of space, which is good online design.
A side issue to "What is it?" is remembering that user may call items by different names than the program
does. You need to make sure many of these terms are included in the index (sometimes as SEE
references) or keyword list, or all the description you care to write won't answer the question.
Why Did It Do That?
Here users want reassurance or problem fixes. Something has gone wrong (or appears to have gone
wrong), and they've encountered a dialog box that was neither expected nor welcome. Well-designed and
well-written text in the error or progress message itself, and solution oriented help text (made available
through a Help button on the dialog). Users are definitely operating the program when these types of
questions occur, so once again, turning to the online help is natural (unfortunately, the workflow is already
http://www.manuallabour.com/Question.htm 5/8/2007

4. Manual Labour Symposia Page 4 of 5
interrupted). As with "What is it?" the answers provided to this type of question should be short (no more
than two screen's worth).
How Do I Do It?
By and large, I do not recommend including procedural information in the online help.** However, if you
can distill the procedure to just enough to fit on one or maybe one-and-a-half screens, using online help as
a procedural reminder become possible. Try to set these window to be automatically "always on top" if
possible--the user needs to refer to them as her or she proceeds.
On paper
Because people generally do not like to read long or complicated pieces of text online, I put the answers to
"Why should I care?" and "How do I do it?" on paper.
Why Should I Care?
Some users do read the manual, and some even take it home (or some other place where their computer
is not) with them. Generally, these users are looking for an overview or an introduction to the program
before they begin trying to use it. They want to feel at least vaguely familiar with the tool from the start.
Information that answers this question is often lengthy or difficult to grasp--you should give every visual
and comfort-type advantage to your users when presenting it.
How Do I Do It?
There is very little that is more frustrating than having to flip back and forth between windows to
accomplish a task, and yet this is exactly what we are asking users to do when we place procedural help
online. Because the information may need to encompass several help screens, the user also has no visual
clue as to how long the procedure will take, or how many steps are involved (unless they have the
patience to skim the information before trying it). In addition, it is substantially easier to mis-read or skip
words online than it is on paper. By putting the procedure on paper, we give users something they can
hold in their laps or leave open on a desktop and follow.
Why Does It Seem Something's Missing?
You may have noticed that I've structured this paper according to the questions I'm endorsing. I will admit
that this is not always an easy formula to follow. Because we are used to stuffing our users like Strasbourg
geese,*** this kind of documentation can seem "too light" or as if there's not enough information. And it can
be easy to leave out needed information. The key to making this method successful lies in insisting (to
yourself, your Subject Matter Experts, and to management) that every piece of information in the User
Guide must answer one of the four questions:
Why should I care?
What is it?
How do I do it?
Why did it do that?
In addition to making sure that all of the answers have questions, try to make sure that all of the questions
also have answers. Information that doesn't fit usually
is not needed by the user
http://www.manuallabour.com/Question.htm 5/8/2007

5. Manual Labour Symposia Page 5 of 5
does not belong in the User Guide (although it may belong in a reference guide, an installation or
Getting Started guide, a tutorial, or even an appendix of the Guide)
You'll find that users get up to speed faster, and are more pleased with the documentation using this
method.
Bibliography
Heckel, Paul. The Elements of Friendly Software Design. New York: Warner Books, 1984.
Sellen, Abigail and Anne Nicol. "Building User-centered On-line Help" in The Art of Human-Computer
Interface Design. Massachussetts: Addison-Wesley Publishing Co., Inc., 1990
* This paper addresses the User Guide (day-by-day information) rather than tutorials (start-up information).
** Bear in mind that I'm discussing ordinary user-guide type help with these guidelines; tools such as cue
cards or Microsoft's Wizards cover extensive information about "How do I do it?" online handily. However, I
feel that they fall into the category of "tutorial," which crosses the online/on paper boundary in different
ways than other items in the documentation set do.
*** except for those of us following minimalist documentation guidelines
About the Author…
Bonni Graham began writing as the "Lone Writer" for Data Trek, Inc., a library automation developer. She
then moved on to Easel Corporation's ENFIN Technology Labs, working on object-oriented client-server
development environments ("OO-La-La"). Currently Bonni owns a documentation business, Manual
Labour, with clients like Hewlett-Packard, Xerox Document Sciences, and Tudor Publishing Company.
For more information on this session e-mail Bonni.
Copyright © Information
This article may not be republished or redistributed by any means or under any circumstances whatsoever without the express
written permission of the copyright owner, Bonni Graham. Single copies of this article may be reprinted for private use and for
review purposes only. Excerpts from this article may be reproduced, provided the reproducing author/editor makes the
appropriate citations referencing the article's original author and date of publication.
Copyright © 1995 Bonni Graham
Send mail to Webmaster with questions or comments about this web site.
Copyright © 2005 Manual Labour Incorporated.
http://www.manuallabour.com/Question.htm 5/8/2007