Advanced Visual Basic Techniques
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471188816
Publication Date: 06/01/97

Types of Help Systems

An application can provide several different kinds of help. Some are very obvious to the user and are quite intrusive. Covering the application with a help screen can be quite distracting. On the other hand, a large help screen can give the user a lot of information very quickly. This sort of help system can also provide advanced features like an index, hypertext jumps to other topics, and keyword searching.

For occasions when the user needs a quick hint but not a full explanation, the application can provide context-sensitive help. By pressing a button or selecting a menu command, the user enters a context-sensitive help mode and the mouse pointer turns into a question mark. When the user clicks on a control, the application presents help for that control and help mode ends. Because context-sensitive help is intended to provide only a quick hint to the user, it should be brief. The user can obtain more detailed information using the screen-oriented help system.

The sections that follow describe these types of help in greater detail and explain how Visual Basic applications can support them.

Building a Help File

Building a standard help file is a complicated process. The Visual Basic 5 Enterprise Edition includes a Help Workshop that makes creating help a bit easier. By default, this program is not installed when you install Visual Basic. You can install it using the Setup.EXE program in the Tools\Hwc directory on the Visual Basic 5 compact disk.

The help compiler provided with the Visual Basic 4 Enterprise Edition is a bit more primitive. The following sections describe the steps needed to create help using this older help compiler. The steps are similar for using the Help Workshop—Workshop just packages them more nicely.

Creating a help file can be described in four steps:

1.  Design the help system.

2.  Create the help topic file.

3.  Create the help project file.

4.  Compile the help project to create the final help file.

Designing the Help System Before starting to build the help system, the help designer should invest some time in basic design. The design should include a list of major topics to be presented. It should indicate where one help topic will have hypertext links to other topics. It should also specify where the user should be able to click on a word or phrase to see a popup dialog giving more detail. Each topic should have a short name. These names or context strings will tie the topics together in the help files.

The description of each topic should also include a list of keywords and phrases that identify the topic for keyword searches. The help system should use many keywords. Because keywords are used only for searching, they do not clutter help topic screens; therefore, the help system should include lots of them.

The help system should not use multiple keywords that are very similar for the same topic. For example, suppose a topic describing database operations has key strings “DATABASE” and “DATABASE OPERATIONS.” When the user searches for DATABASE, the help system will present both key strings because they both begin with the initial string DATABASE. Both keys lead to the same topic, however, so there is no point including them both. The help system could include only the longer key DATABASE OPERATIONS without changing the user’s ability to find the topic.

A convenient way to keep all this information straight is to place each topic on a separate index card or sheet of paper. The card should include the topic’s title, a brief description, its name or context string, keywords, and the names of other topics that will probably be linked to the topic in the final system.

While designing the topics, it is important to remember that people do not read help the way they read a book. They jump freely from topic to topic. Occasionally a user will follow a sequence of topics. More often the user will jump to a topic in the middle of the help file, read part of a single help screen, and then return to the main application.

To make this style of reading easier, each help topic must be as self-contained as possible. Each should be short enough to fit on a single screen. A topic must never assume that the user has just read the previous topic and is familiar with specialized terms. Whenever possible, a help topic should not force the user to visit another topic in order to understand the current one.

If a topic must use an advanced term, it should contain a hypertext link or a popup dialog describing that term so the user does not need to perform a separate keyword search.

Creating the Topic File With a design complete, the help programmer can turn to the actual help content. The content must be stored in a file using the Rich Text Format. The help compiler uses an arcane set of footnotes and text formats to provide help functionality; an editor that can provide these features is required.

Different topics must be separated by hard page breaks. In Microsoft Word page breaks are inserted by selecting the Break command from the Insert menu, clicking the Page Break button, and pressing OK.

Footnotes are used to give the help compiler special information about the help topics. Footnotes are inserted in Microsoft Word by placing the cursor at the beginning of the topic and selecting the Footnote command from the Insert menu. The text of the footnote contains the information being set for the help compiler. The footnote mark tells the compiler what kind of information it is receiving. For example, a footnote marked with a number sign (#) tells the compiler that the footnote text is the topic’s name or context string. Table 2.1 lists some of the more important kinds of footnotes that can be included in a help topic file. The following sections describe some of the other important concepts used by help context files.

Hypertext Links Hypertext links or jumps are displayed as green and underlined when presented to the user. If the user clicks on a hypertext link, the help system presents the corresponding help topic.

Hypertext links are indicated in the help topic file using the strikethrough or double underline format. The context string for the topic that the jump will activate should be placed immediately after the link text. That text should have the hidden format. In Microsoft Word hidden text is visible only when invisible characters such as paragraph marks and spaces are visible. When it is visible in Word, hidden text is displayed with a dotted underline.

For example, clicking on the double underlined DOUBLE_UNDERLINEN text in this sentence would make the help system open up the topic with context string DOUBLE_UNDERLINE.

A common mistake in creating hypertext links is to put a space or paragraph mark between the link text and the context string. In Microsoft Word using copy and paste to copy the context string into position results in a space being inserted before the pasted text. If the context string does not immediately follow the link text, the link will not work.

Popups In addition to hypertext links, the help system can display help popups. The user sees popup references as green text with a dotted underline. When the user clicks on this text, the help system displays a small popup window that contains a line or two of text giving further details about the text. The next time the user clicks the mouse, the popup text disappears.

Creating a popup is similar to creating a hypertext link. The popup trigger string should have the single underlined style. The popup topic’s context string should immediately follow. That text should have the hidden style, just as the context strings for hypertext links do.