GEOS SDK TechDocs
|
| 
4.1 Enabling the Help Editor
| 
4.3 Defining Files and Contexts
If your help text is simple and straightforward, you can probably dive right in and write it. If it is not, though, you should spend some time up front organizing it, naming the contexts and files, and figuring out where hyperlinks will be placed. Defining contexts and links as you're writing can quickly get confusing, even for experienced writers.
Most help text will be configured for Normal Help. This type of help typically has a table of contents page (TOC) and numerous other contexts, many of which are linked to each other. Normally, a help context (page) will be accessible through two means: First, the user could click a help trigger or hit F1 at the right time to bring up the proper context. In this case, the user can not "go back" to the previous context, although he can get to the TOC page by clicking the Contents button. Second, the user could navigate through the help system via hyperlinks and get to the context.
Not all contexts may be available through links, however; some may be accessible only through clicking a help trigger or hitting F1. Other contexts may be accessible only via navigation of hyperlinks in the help document. You should plan this out in advance so you can write effective text and set your links properly.
Perhaps the most straightforward help organization is a simple listing of topics, each of which is a hyperlink to another help screen. For example, the "Change File" help screen in the HelpSamp sample application's default file gives a brief description of the Change File dialog box and then three subtopics, each of which links to another context in the help file. (This screen is shown below.)
A First Aid file, however, is designed differently. It has three "levels" of help: Contents, Chapter, and Article. The Contents page is a TOC page, just as in Normal Help. The TOC button allows the user quick access to that level at all times. When the user selects an entry on the TOC page, a Chapter-level context should be brought up. At this point, only the TOC button is enabled, and the Chapter button is enabled and selected.
The Chapter-level context should similarly list subtopics of interest. When the user selects one of these, an Article-level context will be displayed. At this point, both the Contents button and the Chapter button will be enabled, allowing the user to "back up" to one of those previous levels. Also at this point, the Article button will be enabled and selected. The Article-level context (currently viewed) may contain a list of several questions or subtopics. When the user follows one of these links, the Article button will be enabled but deselected, allowing the user to quickly return to any of the three levels traversed to this point.
First Aid, like Normal Help, may have contexts linked to any other contexts in the same or other files; they are not restricted to the TOC-Chapter-Article links mentioned above.
Simple Help normally will not have any links because it offers no way to go back or even to return to a TOC page. If your application offers Simple Help, you should keep it straightforward and not put in any links.
Although the help controller will change the pointer image when the pointer is over a hyperlink, you should use graphics or highlighted text whenever possible to call attention to the links. Because the Help Editor is extended GeoWrite, anything you can do to normal GeoWrite text you can put in your help files.
Long pages of text can be difficult to read unless you put in headers or other highlighting. Some suggested highlighting techniques are to use colored or gradient-filled text, use the boxed or button text styles, or underline the text. Using different sizes and fonts is also effective. Keep in mind, however, that many users will have monochrome, CGA-style screens.
You can also embed graphics in the text. This does not include using the "graphic layer" of GeoWrite, however--since the Help Editor uses only the text layer, it will not use graphics pasted to the graphic layer. You must paste them directly into the text.
A useful tip to creating consistent help documents is to pre-define a number of style sheets in GeoWrite and use those styles for all your help. Any time a new style is required, create a new style sheet.
GEOS SDK TechDocs
|
| 4.1 Enabling the Help Editor
| 4.3 Defining Files and Contexts