Planning Your Help Approach

Planning Your Help Approach

Developing Help is like developing your software. You shouldn't do it without a plan.
Strictly speaking, you shouldn't do it last. A famous experiment decades ago split a
programming class into two groups. One group was required to hand in a completed user

manual for a program before writing the program, the other to finish the program
before writing the manual. The group who wrote the manual first produced better
programs: They noticed design errors early, before the errors were carved in code, and
they found writing programs much easier as well.
If your application is of any size, the work involved in developing a Help system for it
would fill a book. If you need further information on how to do this, consider the book
Designing Windows 95 Help: A Guide to Creating Online Documents, written by Mary Deaton
and Cheryl Lockett Zubak, published by Que. In this section, there is room for only a
few basic guidelines.
The result of this planning process is a list of Help topics and the primary way they will
be reached. The topics you plan are likely to include the following:
l A page or so of Help on each menu item, reached by getting into What's This? mode
and clicking the item (or by pressing F1 on a highlighted menu item).
l A page, reachable from the Contents, that lists all the menus and their menu
items, with links to the pages for those items.
l A page, reachable from the Contents, for each major task that a user might
perform with the application. This includes examples or tutorials.
l Context Help for the controls on all dialog boxes.
Although that might seem like a lot of work, remember that all the boilerplate
resources have been documented already in the material provided by AppWizard. This
includes menu items, common dialog boxes, and more.
After you have a complete list of material and the primary way each page is reached,
think about links between pages (for example, the AppWizard-supplied Help for File,
Open mentions using File, New and vice versa) and pop-up definitions for jargon and
keywords.
In this section, you plan Help for ShowString, the application introduced in Chapter 8.
This simple application displays a string that the user can set. The string can be centered
vertically or horizontally, and it can be black, green, or red. A new menu (Tools) with
one item (Options) opens a dialog box on which the user can set all these options at once.
The Help tasks you need to tackle include the following:
l Changing AppWizard's placeholder strings to ShowString or other strings specific
to this application
l Adding a topic about the Tools menu and the Options item

l Adding a topic about each control on the Options dialog box
l Adding a Question button to the Options dialog box
l Changing the text supplied by AppWizard and displayed when the user requests
context Help about the view
l Adding an Understanding Centering topic to the Help menu and writing it
l Adjusting the Contents to point to the new pages
The remainder of this chapter tackles this list of tasks.