TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
An embarrassingly long time ago, I requested info on Windows Help
from those of you on this list. A lot of people responded, and now
that Windows Help has come up again, it seems like a good time to
post a summary of all the information I gathered.
As with R. Darren's post, I believe the contents of this summary to
be accurate, but I can't make any guarantees. (Part of the reason
I waited so long to post was that I wanted to find time to verify
more of the items -- I am still looking for this missing time!! If
you see it wandering around, let me know!) =B-o
Thank you to everyone who contributed. Hope you find this helpful!
Faith Weber
EA Systems Inc.
weber -at- easi -dot- enet -dot- dec -dot- com
--------------------------------------------------------------------
WINDOWS HELP INFORMATION
I received quite a bit of information and have (finally) summarized
it under the following categories:
o Information available on Internet
o Magazine Articles
o Books
o Related Software and Utilities
o Miscellaneous Helpful Hints
------------------------------------------------------------
Information available on Internet:
------------------------------------------------------------
Microsoft Help Author (Word for Windows template)
-------------------------------------------------
Directory: /pub/pc/win3/uploads
File: what.zip
Size: Approx. 1.3 MB
Directory: ftp/pub/pc/win3/winword
File: drhelpev.zip (macros for Word 2.0 to convert
doc to hlp files)
I haven't explored these, but this resource was mentioned by two
respondents.
Another respondent says WHAG.ZIP is also available at ftp.cc.monash.edu.au
in the win3/programr directory. He says other WinHelp authoring tools and
information about using WinWord to create WinHelp files is also available
at this location.
According to one respondent, Borland C++ comes with decent documentation
for WinHelp.
PC Magazine: The Independent Guide to Personal Computing (ISSN #0888-8507,
Ziff-Davis Publishing Co., NY) published a series of articles by Ray Duncan
about creating Windows Help files. These articles are in the issues published
from April 1993 through June or July 1993, as follows:
vol. 12, no. 8, April 27, 1993, pp. 325-329
Constructing Your Own Windows Help Files
vol. 12, no. 9, May 11, 1993, pp. 349-354
Building the Basic Structure of a Windows Help File
vol. 12, no. 10, May 25, 1993, pp. 343-354
Integrating a Windows Help File into an Application
vol. 12, no. 11, June 15, 1993, pp. 359-361
Four Techniques to Enhance Your Windows Help Files
vol. 12, no. 12, June 29, 1993, pp. 326-329
Implementing Macros in Your Help Files
vol, 12, no. 13, may also contain an article on this subject, but I
haven't checked.
The author of the articles suggests the Microsoft Developer Network CD-ROM
as an excellent source of information about WinHelp and other aspects of
Windows programming.
WINDOWS Magazine, February 1993
Help is on the Way, by David Claiborne
Includes descriptions of the following utilities used to automate creation
of WinHelp files: Doc-to-Help, QDHelp, RoboHelp, Help Magician, and Universal
Help.
Developing Online Help for Windows, by Scott Boggan, David Farkas, and
Joe Welinske, Sams Publishing (Div. of Prentice-Hall), 1993. $39.95.
This book includes information about planning and implementing
WinHelp systems, as well as information on utilities, and includes a
diskette with WinHelp samples and WinWord macros. [Note: Three respondents
mentioned this book. I bought a copy and it seems to cover the whole process.
No one I corresponded with or talked to knew of any other such books on the
subject.]
Windows Help Authoring Guide, provided on the Windows Developers' CD-ROM
and CompuServe's Microsoft Windows Developers' Bulletin Board. This is
probably the most detailed information available about Windows Help,
but based on my own experience, it seems most useful if you already know
the basics. It also contains a reference guide to RTF.
------------------------------------------------------------
Related Software and Utilities
------------------------------------------------------------
For WinWord users:
-----------------
Doc-to-Help
Automates conversion of documents created in WinWord to WinHelp files.
Intended for people who want to create the manual first in WinWord,
then convert it (or some subset of it) to WinHelp.
Requirements:
Price:
Company: WexTech Systems, Inc.
60 East 42 St., Ste. 1733
New York, NY 10165
212-949-9595
Notes:
RoboHelp
Helps you create help files using WinWord. RoboHelp is a collection of
WinWord macros that help you create topics, establish links, mark up
the document file, and compile the help file.
Requirements: Word for Windows
Price: $495
Company: Blue Sky Software Corp.
7486 La Jolla Blvd, Ste 3
La Jolla, CA 92037
1-800-677-4946 or 619-459-6365
Notes:
Windows Help Magician
For direct creation of help files without WinWord. This product has its own
environment for creating help files.
Requirements:
Price: $199.00
Company: Software Interphase
82 Cucumber Hill Rd
Foster, RI 02825
1-800-542-2742
Notes: Call for a demo disk. This product does not require WinWord, but will
take ASCII or RTF files from Word and other products. One respondent said
this got a good review in PC Magazine.
WordBasic
At least one of the above utilities is a collection of macros for WinWord.
You can write custom macros yourself using WordBasic if you have the time
and inclination. WordBasic comes with WinWord, so it may be a good option
for those who can't afford additional software. The WinWord documentation
contains a section on writing macros, and the WinHelp provided with WinWord
contains enough information to get started. One respondent has used his own
macros exclusively rather than buying third-party products, and
seems satisfied with the results. Others strongly advised finding a suitable
third-party product.
A brief aside:
For those who want to get serious about writing Word macros, Microsoft
Press has published the Microsoft Word Developer Kit. It contains info
about macro-writing for both beginners and more advanced folks, plus a
WordBasic reference updated for version 6, info about the API, etc. It
also includes a goody disk.
For Ventura Publisher (for Windows) users:
------------------------------------------
Master Help
Automates conversion of Ventura Publisher files to Windows Help files. Uses
Ventura's publication file and table of contents to automate creation of
help file structure, topics, etc.
Requirements: Windows 3.1 or later and Ventura Publisher for Windows version
3 or later
Price: $995 first copy at a site; additional copies at same site, $295.
Company: Performance Software, Inc.
575 Southlake Blvd.
Richmond, VA 23236
804-794-1012
Notes: Call for an evaluation copy. A colleague has a demo copy of this
program. I read quite a bit of the documentation but did not use the product.
Judging by the documentation it appears that the product is powerful.
However, to get the maximum benefit from it, you must learn to write macros.
Instructions for this make up the bulk of the manual. Also, you must set up
a different style sheet for creation of help files. Another respondent said
she worked with this product on a trial basis and liked it. She felt it
would be a good alternative to investing in WinWord, which she currently
does not have. MasterHelp seems like a product that's worth trying for
Ventura Publisher users who can take some time up front to learn about it
in detail and write a set of macros to suit their organization's needs.
Note: these are comments made by individuals. I have not verified them.
WinHelp loses some formatting from the WinWord file, such as tabs,
letterspacing, and high-numbered ASCII characters. (Only one respondent
mentioned this.)
The Help Compiler command, HC, will not redirect error messages to a file.
If you want to redirect messages to a file, run the executable itself
(for example, HC31) rather than the HC script.
The hardest aspects of creating WinHelp are designing the system's
structure and deciding how users will navigate through it. Before you
begin, draw a tree representing the structure of the help system, plan the
level of detail of each component, and mark the location of jumps in and
out of each topic.
Look at other people's help files for ideas.
As mentioned earlier, some people recommend that you use third-party tools
to create WinHelp files, while others feel that WinWord alone or in
conjunction with WordBasic macros works just as well.
