LogicSmith
Home - Contact Info - Articles - Files - Links - Adventures - Other Stuff - Dual Monitor Wallpaper
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 any heading.
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 topics.
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 technical support.
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 as links.
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:
closing - application - windows
windows - closing - moving - resizing
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.
Be creative
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 Cline Last Updated Monday, April 06, 2009 Website hosted by 1and1