Building intelligent hypertext help applications

Windows Help

New Microsoft Windows users soon become very familiar with the on line help systems provided in the Windows environment. These use a consistent user interface, typically enabling the user to select from lists of topics to then see further detailed topic explanations. In addition, many applications implement context sensitive help jumps, so that when a help button is pressed on a dialog box the user is shown a context specific topic from a Windows help system file.

This document gives basic guidelines on how a standard Windows help system can be built, and on how to then build hybrid "intelligent" help systems by using this in conjunction with XpertRule.

Since this paper was first written, help systems based on HTML are becoming popular. The principles discussed in this paper apply equally to such systems and the latest version of XpertRule supports calls to external browsers.

The XpertRule® development environment itself contains a standard implementation of a Windows on line help system. When you ask for help within XpertRule, it passes control to the Windows help program - WinHelp - passing also the name of the help file for WinHelp to use and, optionally, a help topic to display (by default the user is shown the main index).

To create such a Windows help system these basic components are needed:

A Word Processor that supports Rich Text Format (RTF), such as Microsoft Word for Windows.
The Windows Help Compiler. This is sometimes provided with programming language packages, or it can be purchased as part of the Microsoft System Developers Kit (SDK).

The basic steps in building a standard help system:

Create the text in Word for Windows, using techniques such as these within the document:
Give each topic a title.
Enter "keywords" against each topic that you wish to appear in the Windows "search" dialog.
Designate (by typically using underlines) the words or phrases where you wish to implement jumps to other named topics, or have pop up explanations appear. You can add the name of the topic to jump to, or pop up, immediately after the word/phrase by using the "hidden text" feature of Word for Windows.
Save the document as an RTF file using Save As.
Pass the RTF file through the Help Compiler, which is used to generate the finished HLP file ready for use.

For this last step, a further important text file is also used, referred to as the Help Project (HPJ) file. This gives a simple text list to the help compiler, telling it such things as the names of the files being compiled, the topic name of the main index and other compiler options. Most importantly, it also provides a list of the topic names where the developer wants to implement context sensitive help jumps. Against each topic name there needs to be a numeric reference.

From within any Windows application (such as XpertRule itself for example) the programmer can pass the name of the help file when help is sought by the user. The programmer can also pass a numeric value to indicate a required help topic.

The list in the HPJ file establishes how this numeric value matches up to a named topic. As the compiler incorporates this list within the finished HLP file, only the HLP file needs to be distributed to users.

Using these basic steps can produce a help system with these benefits:

It is easy to maintain the text in an industry standard word processor such as Word for Windows. Indeed text used in current printed help manuals may already be available in such a format, or easily imported into it.
The user help interface produced is standard and convenient.

However, once such a help system starts to become large and complex a major problem can develop. Help systems need to be built in such a way so that the topics are presented to the user in a comprehensible structure. They should avoid the user going down "blind alleys" or finding themselves sent back to an earlier topic due to "spaghetti" topic jumps! This can be difficult to avoid, as using too few jumps leads to over long topics. It is also very difficult to anticipate how different users might proceed through the same help system.

When building a help system for a piece of commercial software (such as XpertRule) a reasonable structure is often almost imposed upon the help developers. It is usually pretty straightforward that when a particular XpertRule dialog box is being displayed, how to decide which help topic should be called. Similarly, the basic help structure typically follows the structure of the commercial software's pull down menus. This is certainly not the case with applications whose main purpose is to be a help system through and through, as opposed to just supporting another application.

Within help systems it is not effective to start by presenting users with pages of textual information, much of which they may already know. Irrelevant information leads to user frustration and slows down both the advanced and the novice user. Some form of intelligent dialog with the user, perhaps using external data that can be read in automatically, could lead to far more effective and direct use of the information resources.

Using XpertRule, the developer can implement such hybrid systems. For example, using a typical question and answer interface to converse with the user, before directing the help system to jump directly to show relevant information. This enables the help application to act intelligently, as well as jump directly to more technical levels depending upon the knowledge of the user under their current circumstances.

The XpertRule developer has extensive facilities available in order to easily interact with Windows help:

The ability to switch from one help file to another at any point, without the user's involvement. Help systems with multiple HLP files can be implemented.
Developer designed buttons, which can jump directly to a given topic number (using literals or variables).
Developer designed menu lists, where a highlighted item works in conjunction with a help button to jump to a specific topic.
Developer designed help shown as reports. For example, once XpertRule has assisted a user in diagnosing a fault, the repair procedure could be shown in the form of help text.

Used in this way, XpertRule becomes the "structuring tool" for building the help system. The actual help text can now be implemented as source text in the word processor using more simple structures. It also enables complex logic to be separated from volumes of textual information, and to build and maintain this logic in a graphical form.

Windows help systems are often used "side by side" with Windows applications, leaving the help text displayed in one Window as the application runs alongside it in another. Hybrid help applications can often suit this simple but effective approach, with the powerful knowledge based inference of XpertRule interacting with the user while being able to exchange data with other sources. Throughout this process the system can then show Windows help which is relevant to the user's needs.

XpertRule stores knowledge. It is kept in a graphical form to aid maintenance and, as it can be generated as source code, is not locked into any single environment or application. Windows help and Microsoft Word store textual information which, by the nature of these excellent products, aids maintenance and the ability to readily transfer that information. Together this provides an excellent tool kit for the developer of help applications.

Creating RTF files the easy way

The basic Windows help authoring steps described above work quite well. However, there are now many help authoring tools available that make producing help documents much easier - and quicker. One which many of our users and ourselves would recommend looking at is DOC-TO-HELP from WexTech Systems Inc.

Using HTML reports for pop up help

In XpertRule you can use HTML within report windows. If you want to provide simple pop-up help, then using HTML reports provides an alternative to using the more conventional WINHELP.

The report object can be called from Graphical dialogs by adding a button with a macro function to call a procedure. The procedure then just issues a @Do report-name command.

This method of providing pop-up help has advantages and disadvantages:

It is a simple mechanism for pop up help.
You can easily edit and run without needing to compile and manage a separate help file.
You don't need any other external software or tools to develop. Using a good HTML editor can be helpful, as you can copy and paste the HTML source into the report windows. These are often low cost and some are available free. Internet Explorer (version 4.0) includes the HTML editor called Frontpage Express which is ideal for this purpose.
You may need to maintain the help in XpertRule. This is fine for small amounts of help text, but not recommended for large volumes, where using WINHELP or calling a full BROWSER would be more appropriate. However, you could maintain your HTML help pages in another authoring tool (or even a database) and just load them into XpertRule strings at run time. Your HTML report window then only needs to have the string name for the page embedded within the start and end HTML tags.
It is not recommended as a way of implementing large help systems with forward/backward hyper jumps. It is more suited to single pop-ups.
Apart from the OK button, the other buttons on the report window are not appropriate for this type of "pop up help" and should be disabled.