The Five W’s of Online Help for Tech Writers

Lately, I’ve become a vocal critic of modern online help for a variety of reasons. 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 online 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 online 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: Why, Who, What, Where, and When. 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.

The Problem

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 online 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:

• It provides information on other items on a form (dropdown lists and text fields) that have nothing to do with checkboxes, thereby forcing readers to scan through irrelevant information to find the relevant parts. No chunking of the text was done to help readers find the relevant information.
• It does not define how these three items differ, forcing the reader to guess why the two irrelevant entries appear in this topic and how they might affect the choice to use checkboxes.
• There is no procedural information to help readers actually insert a checkbox. For example, how do we display the Forms toolbar, decide which icon to click to insert a checkbox, and use the “Form field options” button (if one can identify its icon) so we can edit a field’s properties? Do we specify the text that describes the checkbox’s function by editing the field properties, or type this text directly in Word? How do we control the position of the checkbox? And so on.
• 

  Figure 2: The "Form field options" help topic accessed using the help system's "find" feature.

  There are no cross-references to take readers to important related topics, such as descriptions of the icons on the Forms toolbar. Moreover, the boldfaced terms misleadingly appear to be hyperlinks to such information; they are not, and boldfacing has been used only to facilitate skimming. Worst of all, searching the index under the words “form fields” only reveals the help topic in Figure 1. Using the search function takes you to the desired help topic, but doesn’t explain any of the options, and because all the search terms are highlighted, it makes the topic resemble a ransom note (Figure 2).

• There is no explanation of why ActiveX controls are recommended, and under what circumstances Word’s own checkboxes would be inadequate.

The Five W’s Solution

Consider how asking a series of questions based on the Five W’s approach could have helped the authors of this help topic to focus on the needs of real users of the product:

• Who will use this help topic? The vast majority of Word users have no knowledge of ActiveX controls, and will never need to use these software widgets. This tells us that information on ActiveX should appear purely as a footnote to the main information.
• Why would someone want to insert a checkbox? Typically, the aforementioned user wants to circulate a Word document to their colleagues to obtain feedback on their preferences. By clicking in the checkbox beside an option, colleagues can express their preferences and return the updated document to its creator. That’s the main task we must describe in our documentation.
• When would they insert the checkbox? Checkboxes differ from other types of “controls” in that you can check (select) every checkbox on a page; where the goal is to force users to select only one of a series of options, you should instead use radio buttons or dropdown lists. We should explain this so readers know that they’ve chosen the right option.
• What does the reader need to do to insert a checkbox? (They must display the Forms toolbar, then work through the process of inserting and modifying a checkbox.) What other options are available? (ActiveX, for one.) This forms the core of the procedural information we must write.
• Where do you find the Forms toolbar, not to mention the various icons on that toolbar that we require to insert and customize the checkbox? This tells us we should provide screenshots of the toolbar or its icons. Although one could argue that tooltips (those little popups that explain an icon if you hold the cursor above it) serve this role, readers will find icons more easily if they’re integrated with the explanations.

Fig. 3

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 online help topic based on these questions might resemble the one in Figure 3.

This solution to the problem represents a first draft that can still be improved, but one that at least solves the problems mentioned earlier in this section. Recognizing that most people who access this topic want to insert a checkbox to let their colleagues select one or more options, we’ve created a topic that focuses primarily on that task, and moved information unrelated to that task (e.g., ActiveX) to the end of the topic, as a cross-reference. Recognizing that there are several selection options available to the user (checkboxes, radio buttons, and dropdown lists), we’ve begun the topic with an explanation that tells readers whether they have selected the correct option; if not, we’ve provided cross-references to related topics that may more closely meet their needs. Finally, we’ve concluded the topic by providing all the procedural information required to insert and customize a checkbox. In short, asking only five questions lets us identify the readers’ needs well enough to produce a considerably more complete online help topic than the one in Figure 2.

Get the Most from the Five W’s for Online Help

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 the user’s 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.

Why?

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 permanent damage to 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 for your online help topics:

• Why would someone use this feature?
• Why would they use a different feature?
• Why might this feature fail to work?

Who?

“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

• let different classes of users find detailed or summary information quickly;
• supply the knowledge readers require to prepare themselves for performing the action; and
• provide a means of obtaining the skill required to perform the action.

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 will use the product or function?
• Who can help them perform tasks they can’t perform themselves?
• Who else will be affected when they use a function or perform a task?

What?

“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:

• What features are available?
• What can we do with a given feature?
• What can we not do with a given feature?
• What are the prerequisites for a feature, both in terms of knowledge and in terms of the steps that must be taken before using the feature?
• What are the consequences of using a given feature?

Where?

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 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 we do produce 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 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 the user selects the text tool. 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:

• Where will the product be used, and what are the consequences of that location?
• Where do users find the menus, keystrokes, or toolbars to activate a feature?
• Where is the product not applicable, and what can users do in that situation?
• Where does the context limit the use of a feature?

When?

“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.

Performing some necessary actions may leave the software or system in a state that requires intervention by the user. For example, setting up “always on” cable or DSL connections, in which the Internet connection generally remain active rather than disconnecting, leaves the connection to the Internet open and thus vulnerable to crackers seeking to gain entry into an unguarded computer. The online help that explains how to keep the connection active should also explain the consequences of this choice. Recommending the installation of firewall software might address this need adequately for those who wish to remain connected.

Consider asking the following “when” questions:

• When does this step take place? (Where does the step fall in a larger sequence of steps?)
• When will the user be ready to do the step? (What are the prerequisites?)
• When will users have the necessary knowledge to complete a step? (What must we teach them before they can proceed?)
• When users have completed a task, is there any cleanup or followup required?

Conclusions

Implementing the Five W’s approach in your technical writing 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 approach 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 on dynamic style guides.

Does the Five W’s approach guarantee that you’ll produce online help 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 approach should not be used blindly. The approach can certainly guide and inform how you identify and solve a communications 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.

References

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.J. 2001. “‘Backing up’ doesn’t mean retreating,” The Official TECHWR-L.
• Raskin, J. 2000. The Humane Interface: New Directions for Designing Interactive Systems. Addison-Wesley, New York, N.Y. 233 p.
• Ray, D.S.; Ray, E.J. 2001. “Embedded Help: Background and Applications for Technical Communicators.” Technical Communication, 48(1):105-115.

Acknowledgment

Thanks to Ed Rutkowski for his comments on an earlier version of this manuscript.