Context-sensitive Help with compiled Help systems - Part 3
By Carol Johnston. Contact us if you would like a PDF version of this article.
Help authoring tools and context-sensitive Help
Different authoring tools have different interfaces for dealing with header files and text-only topics.
Importing a programmer's header file
- Some HATs allow an automated import of the programmer's header file.
- Others require you to (laboriously) type in the context names and context numbers by hand for every context-sensitive topic.
Associating the context names in the programmer's header file with the corresponding Help-related objects in the application
- Some HATs have a simple point-and-click interface for setting-up context name aliases for topics – thus keeping the aliasing process hidden behind the scenes.
- Others require you to know about aliases.
Creating a header file for export to the programmer
- Some HATs hide the aliasing process from the author.
- Some HAT's can automate the context numbering.
- Some cannot directly create the header file. Authors must open the fundamental project text file (.HPJ for WinHelp, .HHP for HTML Help) and copy the relevant information into a new file!
Creating text-only topics for HTML Help
Although these can be created in any text editor, some HATs provide a simple interface for writing them so that the text files are automatically added to the Help project and compiled.
Some produce the required text files behind the scenes as they compile HTML Help.
Help authoring tools and context-sensitive Help
Problems often arise in communication between the Help author and the programmer due to there being inconsistent terminology for the elements involved. Confusion also arises within the Help community due to different authoring tools using different terminology.
The table below shows some of the names that programmers, Help authors and authoring tools use to refer to the elements of context-sensitive Help.
Term |
Synonyms |
Header file |
|
Context number |
|
Context name |
|
Summary
Well-written context-sensitive Help gives users the information they need at the point that they need it.
It involves a simple mapping process:
context number > context name > alias > Help topic
However, problems may arise in its implementation due to:
- inadequate communication between programmer and Help author.
- confusion over terminology.
It is well worth making the effort to overcome these problems, since it gets us nearer to the just-in-time ideal of user assistance.
Subscribe to our Newsletter and don't get left behind
The Cherryleaf newsletter is the world's most popular monthly newsletter on technical communication. It will help you to stay up-to-date on issues facing documentation professionals.
To subscribe to this free newsletter, enter your name and email address in the form below.
"Cherryleaf is one of the best technical authoring houses in the business, and Ellis [the sales director] is profoundly knowledgeable, professional and approachable. Highly recommended for anyone requiring top-notch documentation or training services."
Julian Maynard-Smith, technical author and journalist