Using WinHelp for Publishing & Distribution
"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
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
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
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
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
- 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:
My help screen design objectives included the following:
- Starting with the paper document, use even more headings
- Break up large sections into chunks manageable on the Help
- Convert the graphics into sizes more attractive on the smaller
help screen (see Figure 4).
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.
- Help screens should be clean, attractive and uncluttered
(avoid excessive use of different fonts, small fonts, and too many
- 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
- It's critical that users be able to get where they want
to go quickly and unambiguously, using a minimum of mouse clicks.
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.
[Table of Contents]