|
–Geoff-Hart.com: Editing, Writing, and Translation —Home —Services —Books —Articles —Resources —Fiction —Contact me —Français |
You are here: Articles --> 2002 --> The five w’s of online help systems
Vous êtes ici : Essais --> 2002 --> The five w’s of online help systems
by Geoff Hart
Previously published as: Hart, G. 2002. The five w's of online help for tech writers. <http://techwhirl.com/columns/the-five-ws-of-online-help/>
Lately, I’ve become a vocal critic of modern online help for a variety of reasons. Most of these have already been explored elegantly and in some detail by Deborah and Eric Ray (2001). But my biggest criticism is that despite the usability improvements offered by context sensitivity and modern indexing tools, many help systems become formulaic descriptions of procedures that fail to truly address the needs of their users. This problem arises partially from the inherent difficulty of writing online help, since users may need a range of reference, contextual (e.g., why a dialog box exists), or task-based “how to” information at different times and in different places.
The problem also has its roots in a growing comfort and complacency among writers: we understand reference and task-based information well enough that when we produce help files, we create such material by reflex, without spending much time thinking about what we’re doing. When we write by reflex, following a well-established pattern, we accept and internalize the notions that we must pick which type of information (e.g., reference material versus task descriptions) to provide, and that these two types of information are sufficient for most users of our help systems. In fact, we need to think beyond this stereotype and consider a broader range of user needs.
What does this mean in practice? For decades, journalists have used a proven approach called the “five W’s” to answer the questions that the readers of newspaper articles most commonly want writers to answer. The questions are sufficiently useful that they can easily be applied outside newspaper writing, and I’ve already written about this in the context of audience analysis (Hart 1996). In this article, I’ll show you how you can use these questions to develop more useful online help.
Each of the five W’s is a simple question that starts with the letter W:
Some authorities add a sixth question, “how”, to this list, but “how to” information generally fits under what, where, or when, depending on the nature of the information. Users of online help can benefit greatly from the proven journalistic approach if we can answer these same five questions for each help topic that we create. In the remainder of this article, I’ll provide an example of a failure to ask these questions, show how asking these five questions could have prevented this failure, and provide examples of typical questions we should be asking. Please note that although I’ve presented these five questions in an order that seems logical to me, in practice the approach becomes iterative: it doesn’t much matter where you begin, since answering one question often reveals important aspects of the other questions that you’d not yet considered.
Consider a fairly simple task that appears complicated if you haven’t done it before: creating a reply form in a Microsoft Word 97 document that contains selectable checkboxes; with these checkboxes, people can fill in the form using Word and return it to you. If you open Word’s help file, navigate to the index, and select “checkboxes, inserting”, you’ll see the dialog box in Figure 1. (Assuming, of course, that you click on the “checkboxes” part of this index entry; if you click on the “inserting” part instead, you’ll find to your dismay that the help system displays information on “form elements you can use on a Web page”, which has nothing to do with the desired task, and that provides no cross-references to that task.)
Figure 1. Help text for inserting checkboxes.
The help topic has several obvious and less obvious problems:
Figure 2. The “Form field options” help topic accessed using the help system’s “find” feature.
Consider how asking a series of questions based on the five W’s could have helped the authors of this help topic to focus on the needs of real users of the product:
Asking these questions tells us clearly who will use Word’s built-in checkboxes, why they’d want to do so, what the alternatives are, and how to actually do the job. The revised help topic based on these questions might resemble the one in Figure 3.
Checkboxes let readers of a Word document select one or more items from a list of possible options. If you want to display a range of alternatives but only lets users select one alternative, use a radio button instead. Dropdown lists also limit users to a single choice, but fit in less space on the screen because the available alternatives are only visible when the user opens the list to display them.
To insert a checkbox:
icon on the Forms toolbar.
icon
on the Forms toolbar. Related topics:
Creating checkboxes for forms that will be used on the Web
Using ActiveX controls to link checkboxes with databases
Figure 3. A revision of the help topic in Figure 1 based on the five w’s approach. (Underlined items represent hyperlinks to related topics; they are not active in this example.)
As I demonstrated in the previous section, asking questions based on the five w’s can help you focus a help topic on the reader’s needs far better than if you just describe what readers will see on the screen. Of course, to do so you’ll need to know what types of questions to ask. In this section, I’ve provided examples of how you could think about this task and a list of typical questions you could ask. The list of questions is by no means comprehensive, so use it primarily to start you thinking about how to use this approach, and extend the list of questions based on the unique needs of your audience.
Modern software contains an increasingly wide variety of features. Many of these features satisfy some need expressed by the product’s audience, but many have been added solely to satisfy the Marketing department. Often, the first question to ask when you begin documenting a feature is why anyone would want to use it. Answering that question leads inevitably to “what” questions (the types of tasks for which the feature is useful), but I’ll discuss that followup question in a subsequent section. Here, the why provides valuable information on the context in which the function occurs.
Consider, for example, the task of documenting an “undo” feature. Although some readers will use this feature to let them test the results of an action without worrying about permanently damaging their work (because they can undo any unfortunate consequences immediately), others will use the feature to recover from accidents. Both types of user must understand the limitations of the undo feature and what to do when they encounter these limitations; thus, it’s our job to understand why they might want to use the feature and what this reason says about their mental state. The need to undo an action often leaves users fearful, confused, and perhaps even angry, and that’s how they’ll be feeling when they consult our help file. In response, we must try to reassure them and to provide alternatives if undo doesn’t work. For example, “undo” won’t work for file deletions in most software or operating systems, forcing users to rely on alternatives such as an Undelete utility or a trip to the Windows recycle bin or Macintosh trashcan. If an action can’t be easily undone, we must ask the product’s developers to at least provide a warning: “This action cannot be undone. Are you sure you want to proceed?”
Context can also take the form of exploring and explaining options. For example, most software offers multiple settings for the software as a whole, or for various modes or dialog boxes in the software. Understanding which option to choose requires an understanding of the context in which that option is most valuable (“why would I need to use it?”) so you can explain to readers why they should choose one option over another. In some cases, you can suggest the best option for a given situation, particularly if you know of problems with another option; in other cases, no preferred option exists, and you should explain the consequences of each option so readers can decide for themselves which consequences they prefer to accept.
Consider asking the following why questions:
Why often tells us something about who. When you understand why someone might want to do something, you can often figure out who would and would not want to do that something. In effect, the answers to each why may identify one or more groups within your audience based on whether they have the desire, knowledge, or skill to perform a specific action. Knowing this information, you can design your information to:
Because knowing “who” provides insight into the existence of different groups within your audience, it also tells you how to segregate information for groups defined by different needs and different abilities. Knowing that these groups exist lets you investigate their characteristics further and use the resulting knowledge to define the needs you must meet. For example, if only network managers can perform a certain task, there may be no need to ever let other users of the software know that this task exists. Placing information suitable for use only by network managers into a separate Administration guide may work well. Alternatively, you may need to explain to readers how to contact a specific person (the network administrator) to perform certain tasks for them.
Consider asking the following who questions:
Who tells us about the possible things each group within our audience will try to do with the software and the information we should provide about those things. What questions are familiar to us because they often relate directly to procedural and reference information: “what must I do, in what order, and what are my options?” The most common failing in creating these types of information is that they don’t answer questions based on the other four w’s, and in particular, don’t answer less-common questions that may be unique to each audience or product. For example, if we’re documenting software for maintaining patient medical records, we might need to ask questions such as “what are the ethical consequences of providing access to this information?” and “what steps should we take to safeguard the patient’s privacy?”
Consider asking the following what questions:
Answering what questions often tells us about the context in which software will be used, but explicitly asking yourself where it will be used reminds you to consider the context of that use. Sometimes, it’s crucially important to determine the consequences of working in a specific environment. For example, readers working with handheld computers in a warehouse will find printed manuals far less useful than well-integrated online help, but may need the help formatted for use on a very small screen. Conversely, if they’re working outdoors in bright sunlight, online help may be difficult to see on a typical computer’s screen, and printed “quick reference” cards attached to the computer or carried in a pocket may prove far more useful and usable. Moreover, any online help that we do provide will have to provide high visual contrast, and this may limit our use of detailed graphics or photos. Asking where something will be used may also indicate the need for specific warnings or advice; for example, electrical devices should not be used near water unless they’re sealed and can’t shock the user if they get wet.
Physical context also involves understanding where a tool or function is available: is it reached via a menu, toolbar, floating palette, or keyboard shortcut? Understanding this can provide important insights into describing how to choose tools. For example, if all functions of a program are available from the menus, but only some are available from the keyboard, and even fewer are available from toolbars, your documentation strategy should probably focus on describing how to access functions from the menus; as a result, any reader can operate every feature of the software. To assist users who prefer keyboard shortcuts or custom toolbars, consider providing this information elsewhere, in a single location so that you don’t have to repeat it throughout the printed or online documentation. For example, a well-organized printed quick-reference card or an online index might list all keyboard shortcuts, while a companion visual index might provide descriptions of all toolbar buttons.
Where also addresses non-physical context, such as defining situations where (“contexts in which”) a tool is applicable and conversely, given a specific context, what factors limit the use of that tool. Jef Raskin’s book The Humane Interface (2000) provides substantial information about interface problems, and challenges us to think in several very unconventional ways. Raskin points out that most modern software is strongly modal, which means that how a tool reacts and whether it’s available in the first place depend on which mode the user is currently in. For example, PageMaker’s extensive text-editing tools are unavailable in layout mode until after the user selects the text tool, and inserting a graphic works very differently in the text and layout modes. Understanding how the software’s use of modes supports or conflicts with the user’s approach to doing real work tells you much about how to present the information.
Consider asking the following where questions:
When questions are also familiar because their answers provide an indication of sequence. Some tasks, such as installing or configuring software, require users to perform a series of steps in a specific order so they can accomplish a broader task; each subsequent phase of this task cannot proceed until the previous series of steps has been completed. Other tasks, such as applying formats to text, can occur in any sequence; in a word processor, it doesn’t matter whether you boldface text first or underline it first, since the result is the same in both sequences, but you must generally select the text before applying either format. Understanding whether functions must be performed sequentially or can be performed in any order tells you how to structure your instructions. Where no sequence is required, exploring how the software works may reveal a preferred sequence that works best in all or some situations. Alternatively, there may be no preferred sequence for most cases, yet a limited number of cases may nonetheless have significant (even if not dangerous or difficult) consequences if the steps aren’t done in a certain order.
Understanding what readers need to know before they can perform a task also provides valuable insight into when questions, since it can help you guide users to learn or obtain the prerequisites before they try something new. There’s no point directing someone to information on performing a task if they lack the prerequisites for performing that task. Understanding these prerequisites lets you define what information you must provide before readers can see the actual sequential procedural instructions; for example, you should warn users to back up their data before reformatting their hard disk, not afterwards, and must provide guidance on the necessary tools (e.g., diskettes) and procedures (e.g., offsite backup) that are useful. Similarly, don’t neglect “post-requisites” such as making a backup copy of newly created information or any other consequences that arise after performing a task. (See my article on developing a suitable backup strategy for details.)
Performing some necessary actions may leave the software or system in a state that requires intervention by the user. For example, after logging onto a mail server to collect e-mail, users should be reminded to log off again after they’ve downloaded their mail. This is particularly important in this era of “always on” cable and DSL connections, in which the Internet connection generally remains active rather than disconnecting once the download is complete. The online help that explains how to keep the connection active should also explain the consequences of this choice, namely that the connection to the Internet remains open and thus vulnerable to crackers seeking to gain entry into an unguarded computer. Recommending the installation of firewall software might address this need adequately for those who wish to remain connected.
Consider asking the following when questions:
Implementing the five W’s approach can eventually become sufficiently habitual that you’ll find yourself doing it without devoting much thought to the task. That’s important, because on the face of it, asking these questions for every topic seems to take a lot of time and effort. It doesn’t, but until you become sufficiently familiar with the approach to use it without having to think too hard, it’s helpful to create a checklist based on the five W’s and use that list to test each help topic you create. That analysis lets you confirm that the topic addresses all the reader’s needs. Larger projects may benefit from the creation of one or more standard template files based on the five W’s. Using the appropriate template in the creation of each new help topic eliminates the need for a separate checklist because it directly integrates a topic’s requirements into the template, as I discussed in my article (Hart 2000) on dynamic style guides.
Do the five W’s guarantee that you’ll produce content that meets all reader needs? No. Among other things, this approach only helps you begin to understand what information readers need; it doesn’t always reveal the best way to present that information to meet reader needs (e.g., in the form of a hands-on tutorial or “wizard” rather than as static descriptions of procedures), nor does it provide feedback on whether we’re providing all the answers our audience needs. Finding the most effective form and ensuring that we haven’t missed any questions still requires audience analysis, whether by formal tests or informal discussions with representative samples of our audience. As well, the five questions provide answers with no inherent order, and arranging the answers to efficiently meet the needs of the audience requires some insight on our part.
Last, but not least, learning to apply any approach by habit carries its own risks. There’s an old maxim that if all you own is a hammer, all problems begin to resemble nails. As is true for any tool, the five W’s should not be used blindly. The approach can certainly guide and inform how you identify and solve acommunications problem, but it must support rather than replace the process of understanding the needs of your readers and figuring out how to meet those needs.
Hart, G.J. 1996. The five W’s: an old tool for the new task of audience analysis. Technical Communication 43(2):139-145.
Hart, G.J. 2000. The style guide is dead: long live the dynamic style guide! Intercom, March:12-17.
Hart, G. 2001. “Backing up” doesn’t mean retreating. http://www.techwr-l.com/techwhirl/magazine/technical/backups.html
Raskin, J. 2000. The humane interface: new directions for designing interactive systems. Addison-Wesley, New York, NY. 233 p.
Ray, D.S.; Ray, E.J. 2001. Embedded help: background and applications for technical communicators. Technical Communication 48(1):105-115.
Thanks to Ed Rutkowski for his comments on an earlier version of this manuscript.
©2004–2024 Geoffrey Hart. All rights reserved.