Home - Contact Info - Articles
- Files - Links - Adventures - Other Stuff
This page is taken somewhat from an article I wrote for Software
Development Magazine, and published in their June, 1996 issue. This was also presented at the 1996
SD East Conference.
Organize your topic tree logically
Whether you use the WinHelp 4.0 contents tree or not, it helps to organize your help file into some form
of structure. Before you write a single topic, decide what kind of structure your help file will have,
and what kind of topics you will need (such as conceptual, procedural, definitions, WhatsThis explanations,
examples, tutorials, etc). This will be determined on whether your help file will document an application,
recreate an existing document, or have some other use entirely. The WinHelp 4.0 contents tree shows the
organization of the help file, and can easily expose flaws in the structure.
There are limits to what a user is willing to do to get help. For this reason, you need to balance the
depth and breadth of the topic tree. Don't have long lists of topics under a given heading, and don't
require too many mouse clicks to expand the headings before reaching a list of topics. A good rule of
thumb is to require no more than five clicks to reach any topic, and have no more than ten topics under
Don't bury the critical information
Each application has some information that is critical to its use. This can include keyboard shortcuts,
do's and don'ts, and even technical support phone numbers. This critical information should be as close
to the top of the contents tree as possible and easily identifyable.
Use consistent styles for similar topics
Users love consistency. Your application's dialogs may have the OK and Cancel buttons in the same area
for each, and each paragraph in your manual has the same look and feel. The help file should also exhibit
consistency. Look at the How To topics in the WIndows 95 help file for a good example of topic consistently.
It helps a lot if your authoring tool supports styles and/or templates. Styles make sure that each paragraph
is consistent, while templates make sure the different topic types are consistent.
Have one topic cover one thing for one reason
Topics should be kept short, because the average users would rather not scroll down to find the information
they need. Assuming that the help file is used for an application, the users will use them for one purpose
- to find out how to do what they need to do. They generally want to get in, get an answer to their question,
and get back to the job at hand. Keeping the topics short and to the point will help them find what they
need as fast as possible. If they need access to further information, put that information in other topics
and include links to those topics.
Don't assume linearity
Unlike a book, you cannot assume that a user has seen any topic before reaching the current one. Phrases
like "as we saw earlier", or "except as noted above" should be eliminated. This is
particularly important in help files created from existing documents. Search for any phrases specific
to printed documentation, such as "see page 10", and replace them with links to the appropriate
Use context-sensitivity where possible
When documenting an application, insure that every dialog has a Help button, and that pressing that button
starts the help file at a topic that explains that dialog. If you're using WhatsThis help, insure that
clicking on any control brings up help for that control. This is all necessary in keeping with the philosophy
that you have to get the user the help they need quickly.
Use multiple entry points
Microsoft would have us believe that the application's help menu should consist of two items - Help
Topics and About. The Help Topics entry would start the help file at the contents tab, where
the user could then reach all topics. I disagree with this philosophy.
The user should be able to reach their information as quickly as possible. Therefore, information that
is used often, or has a high priority, should be given its own menu item that jumps directly to that topic.
You could include entries, for instance, for keyboard shortcuts, the glossary, examples, tutorials, or
Don't overload a topic with links
Some topics contain nothing but links to other topics. Before WinHelp 4.0 introduced the contents tree,
this was the only way to build a contents tree hierarchy into your help file. However, this can also be
abused, as seen in the Visual Basic Knowledge Base help file. This help file has literally hundreds of
links from the contents topics, resulting in the user needing to scroll down forever (it seems) to find
the topic they need. Avoid this at all costs.
If your topic is standard text, you should keep the number of links down so that the user is not distracted
by all of the colored hotspots. Current wisdom says that there should be no more than 15% of the text
Cross-reference rather than adding to a topic
There will always be times where one topic is not enough to hold all the information you think your users
will need on any particular subject. Resist the temptation to add all this information in the topic. Instead,
use a related topic link. Under Windows 3.1, you can use a popup containing all of the links. Under 95,
you can use the ALink or KLink macros, which show a dialog with all of the topic titles that have that
particular keyword. With the ALink and KLink macros, you don't need to maintain the list when you add
or delete topics.
Use the spell checker
You probably use a spell checker for any printed documentation or marketing pieces, and there is no reason
why you can't do the same for your help file. If your authoring tool does not have a built-in spell checker,
read the RTF file into Word or a similar word processor and use its spell checker before the final compile.
Avoid unnecessary use of color
Color is great. Too much color, however, results in the Christmas Tree Syndrome, which reduces the readability
of the topic. Since the text hotspots are colored already, you might want to keep the rest of the text
as basic black. In Windows 95, the user can change the background color, and many do. This can render
colored text completely unreadable in some cases. Use bold and italic if you need to emphasize something.
Index as much as possible
All the information in the world won't help your users if they can't find what they need. Help file indexes
are usually added as an afterthought, and the index entries are seldom created by a subject matter expert.
I've heard that 10-15% of your help budget should be spent on indexing. Have as many people critique the
index as possible, including live users if you can.
When using WinHelp 4.0's two-level indexes, use both the noun-verb and verb-noun combinations, such as:
Consider all kinds of alternate terminology (this is where the subject matter expert comes in handy. Remember
that turntables are also known as record players, stereos, and phonographs.
There are lots of things that WinHelp can be used for, with a little creativity. I've seen help files
that were used as cookbooks, Christmas cards, cue cards, or About boxes. If you remember the Windows Resource
Toolkit (a thick book), it contained about fifty pages of troubleshooting flowcharts. It took a programmer
to follow the logic. Well, they reproduced that logic in the Windows 95 help file as a series of topics
with questions, and jumps based on the answers. Now, anyone can easily use it.
If you see a new technique in someone elses help file, decompile it and find out how they did it. Chances
are, they used a creative combination of macros and API calls.
Test, test, test...
They test applications, don't they? The help file is often as complicated as the application. Test all
of the links within the help file. Test all of the links (especially the WhatsThis links) from the application
to the help file. Test all of the links from graphic hotspots. Grab a friend or coworker and have them
read all topics, looking for readability, usability, and just plain errors. When testing, test under different
graphics resolutions (640x480, 800x600, 1024x768), color depths (monochrome, 4-bit, 8-bit, 16-bit, 24-bit),
font sizes (small and large fonts). There may also be problems if the user has changed their system colors
from the Windows defaults. Test under applicable operating systems (i.e., Windows 3.1 help files should
be tested also under 95 and NT).
If your company uses a test automation tool such as Visual Test or QA Partner, the tester can write code
necessary to trigger and verify help topics.
Copyright © 2009 by Dana
Last Updated Monday, April 06, 2009
Website hosted by 1and1