Using WinHelp for Publishing & Distribution

William Pacino

"Hi! I would like to take this opportunity to introduce you to a new electronic magazine available from my Web site. Each issue contains a topic of interest to Windows developers and is distributed as a Windows Help file...."

The example above (italics added by author) is a representative posting from the Internet newsgroup comp.os.ms-windows-programmer.winhelp. This example demonstrates the pervasive nature of Windows Help files. Catalogs, brochures, policy manuals, phone directories--all are now available as Windows Help files.

What started out as a way for software developers to present on-line information and context-sensitive assistance to users has been appropriated for a host of other uses.

Do you want to distribute an electronic newsletter or magazine embedded with your decisions about layout, typefaces, and graphics--and not worry about sending along a compatible file viewer? The Windows Help System has become a publishing and distribution vehicle. Since you can count on the help file viewer and the default set of TrueType fonts being widely available, you can simply post your publication (help file) for people to download.

On-line documentation using the Windows Help System gives the reader instant access to the information, increasing readership and reader response. In addition, on-line documentation can be corrected and expanded at any time, and you can post the new files on bulletin boards for downloading.

The incremental cost of on-line documentation is very low, so you can include longer stories, more examples, tutorials, and more graphic information that the printing and distribution expense might have forced you to omit from a conventional publication.

The Windows Help System supports hyperlinks, keyword searches, browsing, and bookmarks that enable users to navigate to the information they need quickly, find related information easily, and return to the same information later.

In short, the Help System is straightforward to use and to code for, conservatively designed, relatively efficient, and the help file viewer program is bundled free in every copy of Windows software.

Using a Help Authoring Tool

At the most basic level, a Windows help file consists of chunks of text called topics, which are joined by cross-indices called hyperlinks. Just as a book is divided into chapters, a help system is divided into topics. The contents screen of a help file, which is usually the first thing you see when you select the Help menu item in a program (see Figure 1), is simply a topic that consists solely of hyperlinks to other topics that have been arranged to look like a menu. Each topic should cover a single concept, and most topics should contain no more than one screen of text (see Figure 2).

The remaining topics can be thought of as having a tree-like structure in which the second and third levels of the tree often consist of nothing but submenus made up of more lists of hyperlinks. This arrangement permits navigation to a particular piece of information by picking from successively more detailed links. (Of course, most help files also contain hyperlinks across the tree in all directions, so the true logical structure of a help file is more like a network than a tree.)

Using Doc-To-Help

An example of a good help authoring package is Doc-To-Help from WexTech Systems, Inc., which I used to prepare my Windows Help material. Doc-To-Help is very well suited for taking existing documentation and turning it into a Help File. If you understand how to prepare a good paper-based document, Doc-To-Help will take that effort and automatically convert the electronic Word files into a Help file with relative ease.

Doc-To-Help works within Word 6.0 (or 2.0) for Windows. Installing Doc-To-Help on your PC adds several more choices to the existing Word drop-down menus (see Figure 3).

The easiest way to convert manuals into Doc-To-Help format is create a "shell" document based on one of the Doc-To-Help templates and then copy, via the Windows Clipboard, the electronic files from the manual into the "shell" document. Once the files are inserted, you will need to do a certain amount of reformatting.

Briefly, the steps for reformatting are as follows:

Use the menu choice "Tools Repair Manual" to reformat headers, footers, and page layout to match the underlying Doc-To-Help template.
Replace existing styles with Doc-To-Help styles.
Convert tables to Doc-To-Help standard tables.
Reformat graphics.
Remove frames and reposition text and graphics.
Reformat the glossary of terms.
Remove index entries.

A Personal Example

Remember that a well-written paper-based document makes for a more useful and powerful Windows Help file. Of course, a well-written document requires some planning as to audience needs and what is to be communicated about the product or service.

I took a tightly written Word document with graphics embedded in the document and copied this material into a Doc-To-Help template, which permitted me to continue to edit and change the material just as I would in Word. Some of the extra work I did to prepare my material for use in a Windows Help file was:

Starting with the paper document, use even more headings than normal.
Break up large sections into chunks manageable on the Help screen.
Convert the graphics into sizes more attractive on the smaller help screen (see Figure 4).

My help screen design objectives included the following:

Help screens should be clean, attractive and uncluttered (avoid excessive use of different fonts, small fonts, and too many colors).
The file organization should reflect user expectations and should be easy to navigate--there should not be any surprises or dead-ends. Users should be able to move quickly from task-oriented overviews to detailed information and vice versa, and every topic should be searchable under synonyms and aliases.
There should be multiple routes to any desired chunk of information.
It's critical that users be able to get where they want to go quickly and unambiguously, using a minimum of mouse clicks.

After preparing my material, I ran the Doc-To-Help help authoring software to see if my paper document-based material would be presentable in the small Help screen format.

Initially, my material for each topic title was too long. So I had to shorten the material between headings, either by eliminating material not that important to the needs of the help screen user or by adding more topic titles.

I also found that, despite my preliminary efforts, some of my graphics were either too big or not important to the needs of the user. I dropped some of the artwork. For the rest, I spent some time manipulating the size of the graphics (see Figure 5).

Another WinHelp tool of interest is a utility from WexTech called Paper Trail. This piece of software decompiles the entire contents of a Help file, including fonts, character and paragraph formatting, colors, tables, bitmaps, metafiles, SHED graphics, and BAGGAGE files. Paper Trail is useful when the original source files are not available, or for those times when access to all the text and graphics in an existing help file is needed.

What's New in WinHelp 4.0?

WinHelp 4.0 is organized into a three-tab system (Contents, Search, and Find), with the Search and Index features combined into a simplified Search dialog. It is more "book-like," with collapsible and expandable "books" for each topic on the Contents page. The Find feature permits full-text search through all help topics.

From the building side, WinHelp 4.0 uses a different compiler, HCW.EXE; there is a Microsoft-provided "Help Workshop" graphical environment for building help files; the Contents topics are built differently than in WinHelp 3.1; and new A-link and K-link keywords provide extra information-linking possibilities. The WinHelp 4.0 engine will run 3.1 help files, making them look somewhat like WinHelp 4.0 help files without all the 4.0 functionality. If you compile a help file using WinHelp 4.0 and use the new features, the resulting .HLP file will not run under Windows 3.1.

What's New in Windows 95?

Context-sensitive help is no longer provided for the entire dialog box in a single help topic. Help for each individual control is created as a pop-up window and attached to the control itself. However, there are reports of difficulty in getting the pop-ups hooked up because apparently Microsoft has not yet made Visual C++ compatible with WinHelp 4.0.
If you create a contents file (.CNT) to go with your WinHelp 4.0 file, you can get an expandable table of contents with little book icons that open when you click on them.
A two-level index topic replaces the search engine.
Either the WinHelp author or the end-user can generate a database-type file that can be used for full-text search.
You can specify the window in which a help topic appears within the topic definition, so you do not have to manipulate the jumps to get the topic into a secondary window.
Secondary windows can automatically resize vertically so they exactly fit your topic.
You can shortcut buttons to position the user in the dialog at which the procedure starts, eliminating the navigational instructions at the beginning of the topic.
There are fewer help buttons in the dialogs. Those that remain can jump to conceptual information.
Up to nine individual help windows can be open at the same time (from the same help file).
Usability studies by Microsoft indicated that users are hesitant to read procedural topics longer than about four steps, so Microsoft responded by eliminating introductory material and redundant or obvious steps (like "Click OK").

About the Author

William Pacino is, depending on the job opportunity, a technical writer and editor and/or a marketing writer. To see his WWW home page, point your Web browser at http://www.ultranet.com/~wpacino.

[Home] [Previous] [Table of Contents] [Next] [Feedback]