Preparing the Program

Perhaps the most difficult question to answer is when to start developing the documentation. If you start too early, the documentation will be wrong because too much of the software will have changed, leading to a lot of wasted effort. If you start too late, the documentation might not be finished in time or receive sufficient review. You also want to have time to fix any user interface problems that are revealed during the documentation process. A good time to start is when the user interface is fairly stable and the most basic features are near completion. It's better to start too early rather than too late, but starting before this time is probably too early. When in doubt, ask your technical writer.

The next step is to make sure that all screen elements and program activities have descriptive names that are used consistently throughout the program. The screen elements that need names are all windows, dialog boxes, and nonstandard interface objects. You need to have names for the data used by the program, names for the tasks the user performs with the program, and of course the program itself should have a name. Consistency is extremely important. Using several different names to describe the same object confuses everybody and makes the program difficult to document. I discussed what, when, and how to name in Chapter 3, "Establish Consistent Terminology."

Another useful step is to find a model for the Help system. Find an example Help system that you like and that meets most of your goals and use it as a reference point. Try to determine what you like about it and what changes you'd like to make to it. A good model helps you express your ideas with specific examples to your technical writer.

The last step is to prepare a preliminary design of the Help system. Of course, the design of the Help system is something you will negotiate with the tech writer, but you should prepare a preliminary design on your own so that you can express your ideas when you meet with the tech writer. The last thing you want to do is not express your ideas and then be dissatisfied with the results. To prepare the design, review the program and make an outline of the program features. You should highlight the features that need special attention. Such features might be complex or advanced, or they might not be visible directly from the interface.

You need to consider the level of context-sensitive Help you want to provide. While each dialog box should have context-sensitive Help, you have several options in how to implement it. Should there be a Help context for every control accessed through the What's This? button or the Shift+F1 key, as suggested by Designing for the User Experience? Should each dialog box have a single Help context accessed through a Help button or F1 key? Should you support both methods? For property sheets, should there be a single Help context for the entire property sheet, or should there be a Help context for each page?

You should also consider what Help features you plan to support. Will the program support shortcut buttons? Does it need to have troubleshooters? Should it have Tips and Tricks? Note that such help might require support from the program to display a specific dialog box or a specific page on a property sheet.

Lastly, I recommend creating a quick tips list. Whenever I read printed documentation, I highlight the information most interesting and useful to me so that I can quickly review it later. Typically, this information is only a small portion of the total documentation. Since the user cannot highlight online documentation and isn't likely to read it "cover to cover," I like to consolidate the most useful information into a Help topic or set of Help topics and give the user direct access to this information from the program's Help menu.