Automating Development Tasks for a Large-scale Help System

by Bill Lindsay, Senior Consultant

Although tools like RoboHELP® can speed up and streamline the process of creating help topics, there are still many repetitive tasks needed to build a WinHelp system that supports a large, integrated application.

This article summarizes one of the techniques that Fredrickson Communications used to automate the process of developing online help topics. Once the underlying structure and macros were in place, we were able to generate hundreds of help topics at the rate 15-20 per minute.

Setting the scene

The project was a large manufacturing system comprised of five application components. The online help team consisted of a project leader, several information developers, and an editor.

In addition to window-level help, procedures, and other aids such as toolbar help and a glossary, the online help system needed to provide context-sensitive help for about 750 unique window objects (primarily fields) that were used repeatedly throughout the application components.

The primary source of information for the field help was a client-maintained data dictionary that provided information about these objects such as internal (column) names, business names, data types, descriptions, and some notes regarding usage.

Our objective was twofold:

• First, we wanted to use as much of the data dictionary information as we could in developing content for the field help.
• Second, once the content was established, we wanted to create a process for automatically generating the help topics.

Developing the content

Having determined that we could use much of the information in the data dictionary, especially the descriptions, the next task was to define the process that we would use to generate and modify the content.

The major steps were:

1. We identified the data dictionary records that we could reuse for field descriptions. To accomplish this, the first thing we did was to have the writers use an Access database to document field lists for their applications. From this list, we then ran queries to identify a unique set of column data that we could use from the data dictionary.
   Note: For the first release of the application suite, we used about 435 of 1000 records. For the second release, at which time additional application components were added, we used about 750 of 1100 records.
2. Next, we copied the data dictionary records to the Access database. This step included changing some column names, translating data types, and appending the notes to the descriptive information.
3. After the usable information was extracted, the new “Help” table was made available to the writers so that they could modify the existing field information and add further notations to reflect usage considerations appropriate to a particular application or window.

Creating the help topics using macros

At this point, the database Help table contained all of the information necessary to create the field help, such as topic titles, topic IDs, and descriptive text.

The remaining task was to create macros that would actually generate the field help topics for the approximately 750 field objects. From a construction standpoint, although all of the writers contributed to developing the content of the field help, one help developer was responsible for converting the field help information into help topics.

Our solution was a module comprised of three macros.

• Two of the macros were recordable Word macros; their function was to prepare the Word document and create a topic.
• The third was a Visual Basic™ macro that looped through the document and created a topic for each set of field help information.

Starting the process
The Visual Basic macro initiates the process:

1. Before the macro is run, the Help table (containing the updated field information) is copied to the clipboard.
2. When the module is executed, it starts the Visual Basic macro that controls the overall process.
3. The first thing that the Visual Basic macro does is execute Macro #1.

Preparing the document
Macro #1 prepares the Word document:

1. Macro #1 begins by pasting the Help table (from the clipboard) into a Word document.
2. Next, the macro applies styles to the various titles, labels, and text descriptions. A style called “PopupTitle” is applied to each title that will eventually become a RoboHELP topic title.
3. The document is then converted from a table to text.
4. The final step that the macro performs is to remove unnecessary paragraph marks and apply additional spacing as specified.

Creating a RoboHELP topic
Macro #2 adds the footnote symbols and then codes each RoboHELP topic:

1. Macro #2 starts at the top of the document and creates a topic. It uses the title with a style of “PopupTitle” for the topic title.
2. Next, it copies the column_name (a vestige from the Help table), codes it as the topic_ID, and then removes it from the text.
3. Last, other footnotes are added as needed. For example, in our project:
• In order to have an index with a single point-of-entry for a field listing, we applied the footnote K Fields (list of) to each topic.
• Similarly, to display a field help in a small popup-like window named “object” when the topic was accessed from within the Help system (rather than as context-sensitive help from the application), we added the footnote > object.

Completing the coding
The Visual Basic macro uses a loop to complete the coding:

1. Using a loop, the Visual Basic macro runs Macro #2 for each set of field information that begins with the style “PopupTitle.”
2. To prevent crashes due to memory problems, the macro includes a counter that clears the memory buffer by saving the document each time ten topics are created.
3. When the last topic is created, the macro saves the document one final time.

Maintaining the field help

From time to time, the data dictionary is, of course, revised. To update the field help part of the help system, we only have to query the data dictionary for new or changed records, copy this information to our Help database, fine-tune the description information as necessary, and then rerun our macros.

Saving some time

For this particular manufacturing project, from the time the Help table was copied to the clipboard to the time that the last topic was coded, it took less than one hour to generate the 750 field help topics using a low-end Pentium computer. Certainly, before you can use a process like the one described here, someone needs to develop (or extract) the topic content, and ensure that the format of the help topics is consistent from one topic to the next. However, once those things are established, then there are savings to be enjoyed as well as some repetitious tasks that can be avoided.

RoboHELP is a registered trademark of Adobe Corporation.
Visual Basic is a trademark of Microsoft Corporation.