Writing End-User Help Files

---

If you’re working with a large team, you may have the luxury of dedicated user-assistance professionals, whose entire job is to design and create such things as help files and manuals. But on small projects you’ll probably find that you need to be your own help designer. All too often, this task gets relegated to the end of the process, after the code is finished. The result can be a slapped-together help file that’s not really any help—and that doesn’t do more than annoy users.

Rather than treat the help file as an annoyance to be tacked on to an already-finished project, you need to consider it as you’re developing the application. Providing effective help to end users requires you to build hooks for help right into the application, as well as to decide how to expose the help in the user interface. For all but the simplest applications, the strategy of just opening a general help HTML page whenever the user presses F1 won’t be sufficient.

In this section of the chapter, I’ll discuss some of the thinking that goes into an effective help system, and then look at some of the tools that can help you build such a system.

Understanding User Needs

When you’re ready to start developing a help file, keep one cardinal rule in mind:

RULE

You are not the intended user of your own help files.

Presumably you know your own application and its functions quite well, and won’t be the one asking for help. But other people aren’t as fortunate as you in this regard. When you’re ready to start writing help files (or other documentation), you need to think about the needs of the end user. If you watch real users at work with a new application, you’ll find four general reasons why they turn to the help system:

• They just started using the application, and want to know what it does and get an overview of making it do those things. Perhaps they’re not sure whether your application can export data in a format that they need, or they want a step-by-step approach to getting started.

• They’re in the middle of some particular task and need help with that task. Perhaps the user just opened a dialog box for the first time and finds it to be confusing, or can’t quite figure out which choice to select in a combo box.

• They want to perform a particular task but don’t know how to begin. This can happen, for example, when the user has been told that the application contains an embedded web search facility but has no idea how to get to it. If there’s no obvious control on the user interface for this functionality, they’re stuck.

• Something is broken, and they want to fix it. If an error message shows up on screen, or the user gets frustrated and wants to contact technical support, your help should supply useful answers.

If you keep these four reasons in mind, you’ll be able to make your help system more effective. For the first, it’s worth having an overview be the default topic in your help file so that it’s the first thing users see when they open help. If your application is especially complex, you may even want to place a separate menu item on the Help menu to open an overview or a tutorial. The overview topic should also offer easy links to other information of interest to new users, such as tutorials.

For the second reason, context-sensitive help is your friend. If the user clicks the Help button in a dialog box, they’re almost certainly looking for help on how to use that dialog box, not a general help topic. Fortunately, any modern development system will let you build context-sensitive help so that you can take users to the appropriate help topic for their current location in the application.

You need to realize, though, that even writing help for a dialog box takes some thinking. It’s not enough to just describe what each control on the dialog box does. That’s like trying to teach someone to drive by explaining the name and appearance of each control on the dashboard, without telling them how to use the controls. Dialog-box help also needs to contain general advice on what information you’re expecting the user to supply.

For the user who doesn’t know how to undertake a task, you need to take advantage of the index. People tend to look in the index when they don’t know where to find something. That’s because the table of contents organization often doesn’t make it clear what’s located where, and search technology is often confusing to use.

Of course, building an index is also a bit of an art. When you’re creating your help index, be sure to consider all reasonable (and maybe even some unreasonable) synonyms for key terms. For example, you might want to index a topic on searching under “search,” “find,” and “locate.” The problem is that the user won’t know which term your application uses until they find the page in the help system that uses the term. A good index is the best way to break this chicken-and-egg cycle. A glossary can also help the user locate the terms you use quickly, without needing to read through the entire index.

You should also beware of the easy-to-make assumption that you know what your user really wants to do. The phrase “It looks like you’re writing a letter…” wasn’t originally intended as a joke, but it sure worked out that way. Do your best to display the perfect topic when the user asks for help, but do it unobtrusively, and make it easy to get to the rest of the help file if you guessed wrong.

Finally, when the user runs into a snag in your application, do the best you can to be helpful. Your help file should contain examples of all the errors that you expect the program to generate, as well as advice on how to recover from them. If all else fails, make it easy to contact technical support; either the help file or the Help menu should include a clear link to your online support resources, or a phone number if you provide telephone support.

Choosing Help Topics

Users are likely looking at the help file because they want to do something. You can respond to this by making sure that your help is task oriented. In many cases, a step-by-step set of instructions will work better than a long block of text, even if the same details appear in the text. When you’re laying out the page with the instructions, leave plenty of white space and number the steps. Figure 12.1 shows a sample help topic from the Download Tracker help file. Note that the topic opens with step-by-step instructions and postpones some detailed information until the bottom of the page.

Figure 12.1: A task-oriented help topic

Deciding which help topics to include in a help file is something of an art. Here are two rules of thumb that I use to decide which help topics to include:

1. If users invoke help from within the application, they should get help relevant to the task at hand.

2. Major topics that users should understand to make effective use of the application deserve their own help topics.

Showing task-specific help requires determining with the greatest possible specificity what users were doing when they pressed F1 or invoked the Help menu. This is easy to do in dialog boxes but not so easy when the help request comes from your application’s main interface. Knowing which control has the focus provides some clues. In complex cases, you may find it useful to build some history tracking into the application itself. If the user has been working with parts of the application that are related to performing a mail merge, you might want to show a help topic on performing mail merges if you can’t come up with anything more specific.

Major conceptual help topics, on the other hand, tend not to be linked directly to the user interface. Download Tracker, for instance, might offer a help topic explaining the concept of background downloads and a download queue, even though the user won’t need to directly manipulate the queue. Such topics are generally not linked to the user interface. Instead, they might be available as “See Also” links, or definitions that pop up from the task-related help. You can use these background topics to supply additional information for users who need a conceptual framework to understand what they’re doing.

When you’re writing help topics, remember that succinctness is important. Resist the temptation to show off how smart you are and how cool your code is. Remember that users most likely aren’t accessing help just because they want to poke around and learn more about your application. They’re in the help because they’re having a problem. They are likely to be unhappy with the program, stalled in the middle of a task, and ready for immediate answers. The task of the help system should be to deliver those answers, not to brag about your cool implementation of asynchronous events or the Observer pattern. If you simply can’t restrain yourself, put an appendix in the table of contents to hold the technical details—and don’t link to those topics from the user interface.

Organizing Information

Despite your best efforts at context sensitivity, it’s likely that users will end up at the wrong help topic (that is, one that doesn’t contain the information they need at the moment) from time to time. With all of the modern help formats (such as Windows Help or HTML help). you get some standard navigational aids “for free”:

• Table of contents

• Index

• Search

These are all useful tools for the experienced help user, but you can still do more to make the user’s life easier.

For starters, think about how you’re organizing your help as you build the table of contents. The modern help formats support a hierarchy of files and folders to organize the table of contents; you should make use of this hierarchy. Don’t just dump everything into one long list of files with no folders in sight. If users are browsing through the table of contents, you want to give them a small number of choices at each click; the traditional rule of thumb is “seven plus or minus two,” but use that as a guideline rather than a rule. If a topic has only three logical sub-topics, it’s fine to have just three choices. On the other hand, there may be times when 15 choices are appropriate. But if you have a folder that contains nothing other than another folder, or a folder containing 100 topics, you probably need to look at organizing the information differently. Another thing to think about is that some people find scrolling a distraction. Help topics that take up more than a single screen full of information often can be profitably broken up into multiple topics.

Even while you’re organizing the hierarchy, you should remember that not everyone thinks of the world as consisting of a series of hierarchies, even though that seems to be a natural way for a developer to look at things. If you’re using a help format with HTML topics (which is the case with almost every help format today), you can take advantage of the richness of HTML to offer nonhierarchical alternative ways to navigate through your help file. For instance, you can provide links to closely related topics, or even to online websites that offer additional information.

You should also consider supplementing words with visual metaphors. One traditional (though limited) use of this idea entails embedding a picture of a dialog box into the help topic, with hot spots that you can click to bring up help on particular facets of the dialog box. If you’re going to do that, be sure to add a caption along the lines of “Click any control for help on that control.” Otherwise, users will be forced into “mystery meat” navigation, swinging the mouse pointer back and forth across the graphic in the hope that the mouse pointer will turn into the little hyperlink hand—assuming that they realize the graphic has hot spots. In addition to screen shots, you can experiment with hyperlinks from architectural diagrams, tiers of servers, and so on.

But while you’re creating alternative navigation, beware of linking too richly. Everything is probably related to everything else in your mind, but each link is a way for users to leave the topic they’re on and go somewhere else. If your help design contributes to the user getting as lost in the help as they are in the application, you’ve made no progress. In fact, you’ve probably provoked a phone call to your customer support organization, who won’t thank you for the extra work. Every link should answer a task-oriented question that the user is likely to have in the context of the current topic: “If I’m here, how do I do this?”

Note

Depending on your budget, you should consider hiring a professional editor and a professional indexer to aid in preparing your help file. Very few things make a worse impression than spelling or grammatical errors in a help file, which a copy editor can prevent. An indexer will help ensure that you have a truly useful index containing terms users are likely to look up. If you can’t afford such help, at least have someone else read over the help file to make sure there are no obvious mistakes.

Testing and Feedback

Don’t neglect your help system when it comes to testing your application. If it’s difficult to spot your own code errors, it’s doubly difficult to spot problems with your own documentation. As a developer, you may find that much information that seems perfectly obvious to you turns out to be incomprehensible to your users. Having real users (or a good QA department) look over your help can identify these blind spots for you.

Encourage your testers to file bug reports any time they can’t figure out how to do something on the first try. The key pieces of information are what they were looking for and where in the help they expected to find it. Then put that information in that place and go on to the next request. Of course, for this system to be a success you need to develop the help along with the product, instead of tacking it on as an afterthought.

RULE

Plan to start building help files as soon as any part of the product works well enough to require help.

Don’t stop the feedback loop when you ship your product. It’s to your advantage to make it as easy as possible for end users to provide feedback, not just on the help file but on any part of the application. One way to do this is to include a Send Feedback menu item on your Help menu. With the Visual Studio .NET (VS. NET) help, Microsoft went a step further: Every help topic includes a link to send feedback directly back to the writers, as you can see in Figure 12.2.

Figure 12.2: Help topic with a feedback link

Tools for End-User Help

The starting point for building help files is Microsoft’s HTML Help Workshop. A version of this tool that targets the HTML Help 1.3 format is included with VS .NET, although this isn’t the latest version of the format. As you can see in Figure 12.3, HTML Help Workshop itself has a fairly dated look, and although its help files are completely functional, they might not be flashy enough to fit well with your application.

Figure 12.3: HTML Help Workshop

An alternative from Microsoft is HTML Help 2.0, which comes with a new version of HTML Help Workshop that integrates directly with VS .NET. You can download this version as part of the Visual Studio Help Integration Kit (VSHIK) from www.microsoft.com/downloads/details.aspx?familyid=ce1b26dc-d6af-42a1-a9a4-88c4eb456d87&displaylang=en. HTML Help 2.0 is the help format that’s used for the .NET Framework SDK and other recent help files, and it has a very modern look. Unfortunately, Microsoft has announced that it isn’t planning to release the Help 2.0 runtime for redistribution; the only supported use for the VSHIK is to integrate your own help with the VS .NET help. While this is useful for component developers, it’s not much help for applications that will be sold to end users. Microsoft is apparently abandoning this format to concentrate on developing new help formats for Windows “Long-horn,” which is still years off as I write this.

Of course, you’re not stuck with Microsoft tools by any means. The Helpware Group maintains an extensive set of links to help authoring tools and information (Microsoft and otherwise) at www.helpware.net/weblinks.htm. Figure 12.4 shows eHelp’s RoboHelp, one of the high-end tools in the market (now owned by Macromedia). By just looking at the interface, you can tell that RoboHelp has many capabilities beyond those of HTML Help Workshop.

Figure 12.4: RoboHelp 4.1

Even if you don’t want to invest the hundreds of dollars that a RoboHelp license costs, you can still find help-authoring tools that are much superior to HTML Help Workshop at a modest price. One tool I’ve used with great success on small projects is Helpware’s own shareware tool, named FAR (www.helpware.net/FAR/index.html). This $49 shareware tool offers you a variety of aids for creating HTML help in both 1.0 and 2.0 formats, including ways to make the help file web friendly. Once nice feature is that it can take a folder full of HTML files and turn them into an HTML Help file; this makes it possible to use your favorite HTML tool (such as FrontPage or HomeSite) to create your help files.

There’s one more tool that every writer of documentation should be familiar with: the English language (or whatever language the file will be published in). Even if they’re not great writers themselves, users will trip over spelling, grammatical, and punctuation mistakes. People read and comprehend more slowly if the text is littered with errors. Even if you’re doing your own help system development, be sure to get someone who’s good with the language to proofread the results.

---