Old Favorites

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:

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:

My help screen design objectives included the following:

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?

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]