Document to the Question


Published on

This is the white paper I mentioned during my talk. Ignore the web links and address in it, my site is currently down for maintenance. Enjoy!

1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Document to the Question

  1. 1. Manual Labour Symposia Page 1 of 5Symposia•Document to the QuestionWhy Do People Read Manuals?Most software is run by confused users acting on incorrect and incomplete information, doing things thedesigner never expected.–Paul HeckelIf you watch people use software (or anything, but my primary experience is with software), often the firstthing you notice is that everyone has a different random approach to learning and using each programfeature. Given this individuality, how can we ever hope to create user manuals that more than one personcan use?The best way Ive found is to observe people using the product, or performing the tasks the software isintended to replace or facilitate. The more you watch them the more youll see a pattern emerge thatenables you to group information usefully. You may also notice the only constant Ive been able todiscover: people turn to the online help or paper manual only when they have a specific question, usuallyone that they cannot answer by experimentation.An excellent paper in The Art of Human-Computer Interface Design by Brenda Laurel addressed this issuein terms of online help. "Building User-Centered On-line Help" by Abigail Sellon and Anne Nicol discussedsome of the reasons why users dont like to use online help. They discovered two key points (p. 145): The users idea of the problem is often very different than the help or program designers The online help topics were usually designed to match the designers conception, not the users.They used these points to group user questions into five categories and suggest that different help bedesigned for each of the groups.After reading the article, I decided to broaden the authors ideas to include the entire user guide* set: paperand online documentation both. Ive noticed that people seek online help to answer some kinds ofquestions, 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 ofthe kinds of information users seek.Why Should I Care?This question involves basic program theory. In todays business world, software is frequently imposed 5/8/2007
  2. 2. Manual Labour Symposia Page 2 of 5from above, to solve problems that management perceives. The people using the software directly maynot 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 "Whats in it for me?" Even if the user purchased orrequested the software directly, her or she may only have a marketing-brochures idea of why the softwareis useful. Specific reasons for using of specific features still require explanation.Overviews, summaries, and theoretical background information answer this kind of question. For example,youre writing a document describing SQL queries. Information answering "Why do I care" questions couldinclude 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 moneyThe idea is that users want to know why they need to use a program feature. Occasionally, theyll alsowant to know why they need to use that feature in the specific way recommended by the manual (ordictated by the software design).What Is It?This question involves simple description. No matter how "intuitive" the designer, or even most users, thinka 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 buttonsMost users wont push a button or select a menu option, or change program preference defaults until theyknow 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 aresome people to whom it will not be obvious. If the program is a general use program (like a word processoror spreadsheet), this likelihood increases. (Do you know any two writers who approach creating adocument in exactly the same way?)Information answering "How do I do it?" includes Step-by-step instructions Notes, warnings, cautionary statementsUntil users are comfortable with the program procedures, theyre not going to like using it. A good exampleof this is the new version of Corel Ventura--most of the dissatisfied users I hear talking about it cite thenew interface and procedures as a source of their unhappiness.Why Did It Do That? 5/8/2007
  3. 3. Manual Labour Symposia Page 3 of 5Any object, whether its software or a telephone or a microwave oven, occasionally displays unexpectedbehavior. The unexpected is disturbing to users no matter what level of sophistication they posses. If abehavior is weird, but normal, they need to be reassured. If a behavior is the result of an error (either theirown 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 usersare convinced they have "broken" something when they receive an error message, or if a process takeslonger than they expect. They need to hear that everythings all right, or be given instructions on how tomake it so.How Do I Decide Where Theyll Look?Once I devised the questions, I knew I needed a method for determining what information went where. As Imentioned earlier, my primary experience is in writing software documentation, which means that my userguide 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 bothpaper and online information), I have found that users look for entirely different kinds of help from eachmedium. 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] didnt 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 ofthe questions in one medium and the other two in the other.OnlineUsers tend to press F1 (or the system equivalent) to find the answers to "What is it" and "Why did it dothat?" and occasionally "How do I do it?"What is It?Here theyre looking for quick answers, brief descriptions, or reminders of whats required. Theyre usuallyusing the program when these questions arise, so turning to the online help is natural, and does notinterrupt the workflow substantially. Because the answers to this question are generally short, they fiteasily onto one screens 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 programdoes. You need to make sure many of these terms are included in the index (sometimes as SEEreferences) or keyword list, or all the description you care to write wont answer the question.Why Did It Do That?Here users want reassurance or problem fixes. Something has gone wrong (or appears to have gonewrong), and theyve encountered a dialog box that was neither expected nor welcome. Well-designed andwell-written text in the error or progress message itself, and solution oriented help text (made availablethrough a Help button on the dialog). Users are definitely operating the program when these types ofquestions occur, so once again, turning to the online help is natural (unfortunately, the workflow is already 5/8/2007
  4. 4. Manual Labour Symposia Page 4 of 5interrupted). As with "What is it?" the answers provided to this type of question should be short (no morethan two screens worth).How Do I Do It?By and large, I do not recommend including procedural information in the online help.** However, if youcan distill the procedure to just enough to fit on one or maybe one-and-a-half screens, using online help asa procedural reminder become possible. Try to set these window to be automatically "always on top" ifpossible--the user needs to refer to them as her or she proceeds.On paperBecause 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 computeris not) with them. Generally, these users are looking for an overview or an introduction to the programbefore 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 visualand 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 toaccomplish a task, and yet this is exactly what we are asking users to do when we place procedural helponline. Because the information may need to encompass several help screens, the user also has no visualclue as to how long the procedure will take, or how many steps are involved (unless they have thepatience to skim the information before trying it). In addition, it is substantially easier to mis-read or skipwords online than it is on paper. By putting the procedure on paper, we give users something they canhold in their laps or leave open on a desktop and follow.Why Does It Seem Somethings Missing?You may have noticed that Ive structured this paper according to the questions Im endorsing. I will admitthat this is not always an easy formula to follow. Because we are used to stuffing our users like Strasbourggeese,*** this kind of documentation can seem "too light" or as if theres not enough information. And it canbe easy to leave out needed information. The key to making this method successful lies in insisting (toyourself, your Subject Matter Experts, and to management) that every piece of information in the UserGuide 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 questionsalso have answers. Information that doesnt fit usually is not needed by the user 5/8/2007
  5. 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)Youll find that users get up to speed faster, and are more pleased with the documentation using thismethod.BibliographyHeckel, 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-ComputerInterface 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 Im discussing ordinary user-guide type help with these guidelines; tools such as cuecards or Microsofts Wizards cover extensive information about "How do I do it?" online handily. However, Ifeel that they fall into the category of "tutorial," which crosses the online/on paper boundary in differentways than other items in the documentation set do.*** except for those of us following minimalist documentation guidelinesAbout the Author…Bonni Graham began writing as the "Lone Writer" for Data Trek, Inc., a library automation developer. Shethen moved on to Easel Corporations ENFIN Technology Labs, working on object-oriented client-serverdevelopment environments ("OO-La-La"). Currently Bonni owns a documentation business, ManualLabour, with clients like Hewlett-Packard, Xerox Document Sciences, and Tudor Publishing Company.For more information on this session e-mail Bonni.Copyright © InformationThis article may not be republished or redistributed by any means or under any circumstances whatsoever without the expresswritten permission of the copyright owner, Bonni Graham. Single copies of this article may be reprinted for private use and forreview purposes only. Excerpts from this article may be reproduced, provided the reproducing author/editor makes theappropriate citations referencing the articles original author and date of publication.Copyright © 1995 Bonni GrahamSend mail to Webmaster with questions or comments about this web site.Copyright © 2005 Manual Labour Incorporated. 5/8/2007