Useful Information

Free guide for Project Managers on planning documentation projects

Sent out as series of emails. Use the form below if you’d like to receive this guide:

Aligning documentation with your business

Sent out as series of emails. Use the form below if you’d like to receive this guide:

Subscribe to our Newsletter

For free advice and news on technical communication, join the thousands who receive our newsletter.

Your details will never be shared with anyone, and you can un-subscribe at any time.

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	map file mapping file
Context number	context ID map ID map number mapping number UID (unique ID) GUID (globally unique ID) Help ID
Context name	context string symbolic constant constant define macro topic ID

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.

For free advice and news on technical communication, join the thousands who receive our newsletter

technical authors, newsletter

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.