Editor’s Note: This is a reprint of an article originally published in 2000. However, many of the key concepts retain a great deal of value.
My first epiphany about online help struck while I was browsing through the latest release of a popular Windows program. After exploring for a few minutes, I stumbled across an interesting option that hadn’t appeared in the previous version (let’s call this “option X”), and my curiosity was piqued. With the confidence of every naive Windows user, I hit the F1 key, certain that enlightenment was only a few words away.
My optimism dwindled when I read the corresponding instructions in the online help, which went something like this:
“To enable option X, click once on the option X checkbox. To disable option X, click the option X checkbox again to remove the checkmark. Click OK to save your changes.”
Clearly something was wrong here. I had a vague understanding that the online help had somehow misunderstood my intentions. I wanted to know what option X actually accomplished; it wanted to explain to me, in oddly explicit detail, how to use a checkbox. It seemed to me that the function of option X was not at all obvious, and yet the way to use a checkbox–a standard Windows interface element–was an instinctive part of every computer user’s understanding. If I didn’t know how to use a checkbox, I probably wouldn’t have guessed to press the F1 key for help, or even known how to start the application in the first place.
What Went Wrong?
At the time, I didn’t give it much thought. But ever since, I’ve been encountering variations of the same unhelpful instructions, in the help systems of nearly every major software vendor. Often the problem appears in a more subtle variation, as in these examples:
- The information about “option X” is shown in the help topic, but in the middle of a series of steps that tells me how to load the preferences window (even though I pressed the F1 key from the preferences window).
- The information about option X is shown in the instructions for the task that it affects. In other words, if I’m hoping to learn about option X, I’ll have to first guess what feature it’s related to, or search through the help system.
- When I press F1, I’m presented with a list of topics about configuring various aspects of the program. Only after jumping through a few topics do I stand a chance of finding the information for my current window, buried deep in a task-specific procedure.
When I started to create my own online help and printed manuals as a technical communicator, I found out what had gone wrong. Online help was suffering because it was being carved out of the same material used to generate the printed manual.
In a printed manual, users expect a wealth of detail and a task-based approach that guides them around different parts of the application. There is no use telling them what each option in a window is for; instead, the manual aims to help them determine what options to set based on the task they are trying to accomplish. Users of online help, however, tend to be more familiar with the program. They expect to be able to use the help to quickly gain specific information about the elements in front of them, and fill in the gaps in their knowledge.
Instead of restructuring the information for online users, the software companies that were making the infamous “option X” software were trying to wedge task-specific procedures into context-sensitive help. They had probably ignored the problems caused by this bit of desperation because they were busy wrestling with some of the other issues of single-sourcing, like the vastly smaller information bandwidth available in online help.
Is Online Help a Waste of Time?
Context-sensitive disasters like these have caused quite a few technical communicators to claim that single-sourcing (the process of using the same content to create help files and printed material) is a mistake. It’s led other writers to argue that the usefulness of online help is severely limited, and that we should think about writing more books. Both arguments have a grain of truth, but they also reflect plain and simple frustration resulting from the current-day avalanche of bad help.
We need single-sourcing. While single-sourcing introduces a web of complications, not single-sourcing can be a whole lot worse, resulting in help files and printed manuals that are perpetually out of sync and condemning technical communicators to a life of laborious reformatting. In fact, technical communicators who don’t implement a single-sourcing strategy often become so resentful at having to maintain separate copies of similar content that they allow their help files and manuals to atrophy. Though they may have new ideas about how to improve explanations or organization, the tedious editing job involved makes even the hardiest soul reluctant to make a change.
Online help does not compete with print. Printed books are an ideal way to present a large amount of information in a helpful and even entertaining way; however, printed books don’t compete with online help systems. Help systems belong to the family of application support. They are just one way that information can be integrated into the computer environment in order to make a user’s day-to-day life easier. A book may be the perfect teaching instrument, but context-sensitive help is unmatched for presenting timely information. It beats any paper-based reference for helping users sort out a problem or answer a question while using a program they already understand.
Structuring a Document to Head Off Disaster
To avoid disaster in context-sensitive help, we have to abandon some of our current single-sourcing habits, and restructure our information so that it can exist comfortably online and in printed matter. Easier said than done, right?
Below I indicate some principles that can help keep things straight. These tips assume that you are starting with printed documentation first, and then converting it to a help format. For many reasons, including the fact that help has a much looser structure than print, this is usually the best approach.
Divide tasks into procedures and parameters. Most good manuals include procedures: Numbered steps that describe how to accomplish a single task. Along the way, somewhere between the steps, information about the options in different parts of the program creeps in. For example, a list of steps explaining how to print a document might add a quick note about paper orientation. The problem with this approach is that the paper orientation information is now trapped inside a procedure. It’s helpful if the user is reading the procedure, but otherwise it’s not easily available. This can cause the following problems:
- If the user needs to understand the concept for another task, the information will need to be repeated.
- In a context-sensitive help system, a user who needs information about paper orientation is forced to wade through a procedure that includes several unnecessary steps.
To resolve this problem, you must organize your information in a structure that accommodates both print and help. A good way to do this is to divide the procedure from the parameters. For example, you could divide the printing task into a procedure called “To print a document” and another section called “Print Options.” The “To print a document” section would be a list of steps, with a note informing the reader that information about the various print options can be found in the following “Print Options” section. The help file would use both the list of steps and the parameter information, but you would link the application’s print window to the “Print Options” topic, not the list of steps.
Alternatively, try to structure your document so that you can include information in the procedure as a specific example, alongside a more general reference. You’ll find that it’s easier to filter down the content when you convert to a help file than to add missing information. Remember, the last thing you want to do is to make an ugly compromise by using the procedure in the context-sensitive portion of your help.
Recognize that help has its own conventions. The printed book is one of the most flexible formats for presenting information. In even a carefully structured manual, there are often several different ways of organizing content in each section. Many a mildly bored technical writer has used this as a license for creativity. Be forewarned: These diversions will haunt you in a single-sourced project. Rigid structures are an absolute requirement; rely on skilful writing to make the content interesting.
Use an automated tool. The ideal of single-sourcing is to streamline the conversion of content into different media. If you need to use a complex import procedure that involves manual steps, you’ve already compromised your single-sourcing strategy.
When developing a single-sourcing strategy, spend three hours developing an automated strategy rather than one hour making manual changes that will need to be repeated again and again. Two excellent automated tools are Quadralay Web Works Publisher, which converts FrameMaker documents to WinHelp and HTML Help, and DocToHelp, which performs similar magic with Microsoft Word documents. No one has quite convinced me that RoboHelp and ForeHelp, which are otherwise excellent help authoring tools, can be used for flexible single-sourcing.
Recognize the limits of your context. Context-sensitive help presents the best possible topic to the application user, based on the window that is currently displayed; however, depending on what window this is, you may not actually know what task the user is involved in, and what information should be provided. For example, if a user presses the F1 key from Microsoft Word’s main document view, the help program has no choice but to present a list of possible topics, or a default “welcome” topic.
To make successful context-sensitive help, you must understand this restriction. Don’t show a default topic that might have what the user needs. Instead, design a special intermediary topic for every window that has more than one possible use. This intermediary topic should include a description of the window, if necessary, and a list of links to all the possible tasks. Intermediary topics will not be part of the printed source. Instead, you should put them in a separate file, and include them when you convert your printed documents.
Remember, to use intermediary topics successfully you must understand where they are required and where they aren’t. Many programs create a “context-sensitive disaster” by using intermediary topics for every window, including program preferences, printing, and so on.
Final Thoughts
As you delve into the single-sourcing puzzle, it will become more and more obvious that technical communicators have two distinct roles. The obvious role they play is that of a content creator who writes the material users need to learn. The more subtle role is that of an information designer who plans the way that content is presented. Context-sensitive help challenges the best information designer to plan out new ways of structuring knowledge. The reward, however, is great: The ability to present the specific information users need when they need it, without forcing them to stop working, pick up a book, and search for information.
