Programming Tools:prgtools

Planning online help Foundation

Each online help begins with a help project file. It is created by a Help Workshop and has the file extension HPJ (RTF-based help) or HHP (HTML-based help). A project file contains all information required to create an online help file. This includes names and location of the source files to be compiled, the file name for the table of contents (CNT or HHC file) plus the file name for the index, if applicable (HHK file). The files for table of contents and index are usually created directly after the project file.

The quality of an online help depends not only on the contents of the presented text but is influenced to a high degree by how fast a user can find a particular information. When planning an online help the different possibilities of accessing the help system should be taken into consideration. Windows help systems offer the following four possibilities:

Context-sensitive help
Help index
Table of contents
Full text search

Context sensitive help: This is the fastest possibility with which a user can retrieve the right information about any part of a program. However, it also requires the most effort and careful planning since both program development and documentation are closely linked to each other. Each Xbase Part for which a separate help text is planned must get its own XbpHelpLabel object which selects the corresponding help window. If the documentation and the program code of an application is written by different persons, a close cooperation between program developer and help author is required. Also, context sensitive help must be available consistently throughout an application program to be accepted by the user.

Help index: If a program has no context sensitive help, the help index becomes the most important connection between help system and application program. Users tend to access the help index first when searching for a particular information. The planning of a meaningful and well-structured help index should receive special attention. For example, it is a good idea to prepare a list of keywords which should be included in the help index. When the help texts are written, these keywords can be used in different places describing a similar context. Also, window titles are good candidates for inclusion in the help index since they refer directly to the application program. A corresponding help text should then include a description of the window contents plus information on how a user can open the window. It is also good practice to include synonyms in the help index so that information can be found using different keywords.

Table of contents: Each online help should be equipped with a table of contents which shows the structure of the help system and its topics. This gives a user the possibility to get a quick overview about different aspects or the functionality of an application program.

Full-text search: Windows help systems offer a full-text search possibility where a single word is searched for in the entire online help. The full-text search feature must be selected in the HTML Help Workshop when the help files are compiled. With the RTF-based help, however, it can be installed by the user. Although full-text search is powerful, its significance depends on how often the searched word exists in the online help. All help pages which contain the word are listed. As a consequence, users access the full text search mostly as the last possibility for searching.


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.