Building Help in Windows

["Doug, Data Librarian at Ext 4225" <engstromdd -at- PHIBRED -dot- COM>]

Terry McNinch asks for advice on on-line help for Windows users:

*************
I need to build on-line help for a Windows application that will be
distributed without cost to federal, state, and local public agencies,
schools and universities.

Is WinHelp the only way to go or are there other options? We can not count
on the users having MS Word or some other wordprocessor that runs the help
system.
*************

There are other options, but it sounds like WinHelp is the best choice in
your situation.  Definitely, you want to avoid anything with a per-viewer
liscensing fee or restrictions; it would be pretty silly, not to mention an
administrative nightmare, to have a free application with a fee for the
help viewer.  WinHelp has the advantage of being available with every copy
of Windows, and it's conventions are widely used and understood.

A word processor is not an issue for *reading* the help file.  The WinHelp
viewer (sometimes called the "engine") is a completely separate program
called WINHELP.EXE, which is included with every copy of Windows.
WINHELP.EXE renders the document you create (an .HLP file) on the screen
for the user, just as WINWORD.EXE can display a WinWord document file, or
EXCEL.EXE can display and manipulate a spreadsheet.

However, unlike WinWord and Excel, which can create, manipulate and display
their respective files, WINHELP.EXE only displays files.  To create and
edit the .HLP files, you need some sort of authoring tool and a copy of the
Help Compiler.

There are at least three elements to a Windows help project:  an .RTF file,
containing text (and possibly graphics); a .HPJ (Help Project) file, which
is an ASCII file containing compiler instructions; and finally the Windows
Help Compiler, which uses instructions in the Help Project File to turn the
.RTF file into a .HLP file. The .HLP file is what you will give the users.

WinWord (and several other word processors) are capable of creating
perfectly good .RTF files, and it is possible to create a Help File with
nothing but WinWord and a trusty copy of the Help Compiler you've
downloaded from an FTP site or CompuServe (or picked up from a Software
Development Kit, Developer's CD, or Distribution Kit).  However, I've done
this and I don't recommend it.  While it's possible to create a file this
way the first time, it's nearly impossible to maintain it.

The reason is complexity.  The Help features (jumps, pop-ups, keyword
search, etc.) are created by placing commands in the .RTF file.  For
example, search keywords for a topic are designated by creating a footnote
with the "K" symbol, and then placing the words you want to search on in
the footnote.  Jumps are created by double-underlining text, then placing
the name of the context string for the target topic in hidden text
following the jump.  Minor miskeys can goof almost any of this up, and it's
frustrating to go back later and figure out what you did without a central
listing of, say, keywords and browse sequence numbers.  If you're a
WinBasic guru, it's possible to write macros that handle a lot of this, but
that's pretty time-consuming, too.

For that reason, lots of folks have created authoring tools that tie
together some of the elements and automate parts of the process.  For
example, most tools allow you to highlight text, and press a toolbar
button to create a jump, rather than typing everything by hand.  Most also
smooth the seams between the .RTF file, the .HPJ file, and the compiler,
making it all seem more like a single project.

The low-cost/low-feature route is WHAT (Windows Help Authoring Tool), an
unsupported application from Microsoft, available from the Developer CD,
FTP sites, and possibly CompuServe and SDK's as well.  It's more or less
free, and basically worth the price.  It cleans up and automates some
WinHelp authoring tasks, but doesn't take on the really thorny issues, like
managing browse sequences, in a meaningful way.

To get real functionality, you're going to have to drop several hundred
dollars on a real tool.  Most (but not all) tools are shells that add some
functions to WinWord that turn it into a full-blown authoring tool instead
of just a .RTF editor.  After an extensive evaluation, our writing group
chose HelpBreeze from SolutionSoft (999 Evelyn Terrace West, Suite 86,
Sunnyvale, CA 94086. Phone: 408 736-1431).  It addressed all the issues we
thought were important, offered decent technical support, and was open to
the idea of a concurrent-use site liscense, which was important to us.
I've been using it for a couple months and supporting some of the local
users, and it seems to be going pretty well so far.

There are lots of other great tools out there, and more are coming on the
market every day, so the only real answer is to look around. Hopefully,
people with experience with other authoring tools will write to the list
and describe what they like and dislike about "their" tool.

The only system I've used besides HelpBreeze and WHAT is Doc-to-Help.
It's slick in that you can basically ignore the fact that you're writing a
help file, and write a printed manual instead.  Macros then convert your
print document into a help document. The resulting source file can be used
for both your printed document and the WinHelp file, which can be a real
timesaver.  However, I found the structure rather rigid to work with, and
we grew disillusioned with WexTech because of repeated delays in shipping
a version compatible with WinWord 6.0.  We may give them another look
after they've proven they can deliver.

I hope this helps,

Doug
ENGSTROMDD -at- phibred -dot- com