Document to the Question
1 like370 views
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.
![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](https://image.slidesharecdn.com/d2question-121017150409-phpapp01/85/Document-to-the-Question-3-320.jpg)
Document to the Question
- 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