There are a number of help file formats: The most common is HTML Help, which is used by applications that run in Windows. (An older format, WinHelp, is no longer supported. ) Apple and Unix each have their own formats, as well, as does Sun Microsystems, with its JavaHelp. Software applications designed to run under several operating systems may use a cross-platform help system that runs in the user’s Web browser. Whichever help authoring tool you use should support the help format(s) you are going to create help files in.
The contents file includes the text in the help file that explains how the software application you are documenting works. The text is usually broken down into topics that cover a specific screen, feature or procedure. The index file is a list of the help file’s topics. It is used to create a table of contents that users can use to select a topic to view, as well as a searchable index within the help file. Image files are graphic files of program screens or portions of those screens displayed within the help file to enhance the users’ ability to understand what the help file text is referring to.
Help files can also have, in addition to the main window, secondary windows that describe a particular feature in detail and automatically sizing pop-up windows that give short descriptions of features. Help files can also include embedded text that appears only when highlighted text or a button is clicked.
While you can build the table of contents as you go, it helps to have some plan for how to organize it. You can organize the table of contents around the program’s screens, its features, ways to use it or some combination thereof. As you write the topics, consider other information in the help file that users will want to have quick access to. You can create jumps, or hyperlinks, in the help file text that connect to the topics that have that information.
Text and screenshots should be laid out together in a topic such that users can see the screenshot and its supporting text without undue scrolling. In many cases, you’ll want to show a portion of a program screen instead of the entire screen, or show the screenshot in a smaller size than the original. Your screenshot application should be capable of resizing the screenshot without blurring or loss of detail. If you anticipate changes to the user interface between the test and final versions of the program, you may want to hold off on creating screenshots until you have the final version of the program to work with.
On larger help file projects, compiling and testing are ongoing processes. You’ll want to compile the help file and check your work several times before creating the final version.
