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.
Subject:Summary: Help On Help! (long) From:"Jarvis A. Ridges" <Jarvis_A -dot- _Ridges -at- POSTAL -dot- ESSD -dot- NORTHGRUM -dot- COM> Date:Thu, 14 May 1998 11:05:13 -0400
This information has been posted to both the Techwr & Winhlp lists.
I'd like to thank everyone for responding to my questions about online
help, etc (see recap below). I have been asked to post a summary of
Question 1: When creating a "help" option for each of these
apps, is this considered online help or does online help become
online help when it is placed on an inter/intranet? (Please
forgive the simplicity of this question).
* Online help is what you see bundled with other Windows apps.
It doesn't necessarily have anything to do with HTML-based
* Online help is any help or HTML file that is accessed
directly from an application. Online books are help or HTML
files that explain the application, but are not necessarily
accessed from it --- basically an online version of your
manuals. None of these need to be accessed from an
inter/intranet connection to be considered online.
* Online help is not just on the inter/intranet, but help that
appears on the screen, rather than in a manual.
* Online help is considered to be help attached to an
application - it is electronic rather than paper-based.
Question 2: The move seems to be towards HTML-based help.
Should I begin there or should I start with WinHelp and convert
in the future?
* RoboHelp can be used to create WinHelp. It can be converted
to HTML Help with a click of a button (or two) later.
* One respondent observed that with the introduction of
Windows 98, there will be a major migration towards HTML help.
But, if you're using Blue Sky's RoboHELP and RoboHTML
products, the conversion from one to the other is VERY easy.
(S/he also suggested that I talk to the programmer about the
future of the project, and that I'll likely be OK with regular
* The move to HTML Help is strong, but has some serious
restrictions. The worst (best?) of these is that you must
have IE 4.0 installed on your users machines to use it. Also,
HTML Help is still in it's infancy and is undergoing quite a
few growing pains. Plus, there's the HTML learning curve. If
you have the time and can guarantee your users will have IE
4.0 or later, go for it. Otherwise, stick with WinHelp. The
conversion process is fairly smooth. Extensive discussion on
the pros/cons of HTML Help can be found in the archives.
* Another suggestion was to start with WinHelp and convert in
the future. RoboHelp 5 and higher versions especially make
this easy to single-source, because you can compile any of a
variety of types of help from the same source files.
* With one tool, Doc-To-Help version 3, all of your help
options are covered. Doc-To-Help utilizes a single sourcing
methodology that allows the author to prepare output for:
Windows Help 3.0/3.1; Windows NT 3.51/4.0; Generic HTML; HTML
Help; Java-enabled HTML Help; Active X-enabled HTML Help;
Compiled HTML Help. In a recent review of the four major Help
Authoring Tools, the Philadelphia-Metro chapter of the STC
ranked Doc-To-Help the best overall Help Authoring tool,
including converting help files into HTML; see http://stc.org/region2/phi/n&v/index.html.
Question 3: Someone indicated on the list that the training
documentation should be different from the manual, and they both
should be different from the online documentation. Should I
continue to use MS Word to create my printed documentation?
(Eventually, we'd like to place the manuals on our company's
intranet. However, I'd like to have hypertext links within the
manuals that would jump from document to document, and our System
Admininstrator said that this isn't possible with .pdf files.)
* One suggestion was to write the manual first, and then pull
whatever was needed from it to develop help and training.
* One organization uses Word to produce both online and
hardcopy documents. If your users are all on Windows NT/95,
posting .hlp files on the intranet shouldn't be a problem;
.pdf files are mainly used because they print nicely and are
platform independent. If those things are not a concern, the
.hlp files can be linked as well as HTML files - which are
also platform independent.
* In a nutshell, training teaches the user how the software
works and how to take advantage of that functionality;
hardcopy docs provide high-level overview and task-level "how
to"; online help provides only "how-to" on demand. (It was
also suggested that I continue to use MS Word for hardcopy
docs since I'm already doing so, and I'll have several easy
option for converting the Word docs for inter/intranet use.)
Word has it's own HTML export process, that "should" preserve
internal links like the cross-reference and TOC features.
* The recommendation between the different mediums refers to
the structure of the document and not the content. With
Doc-To-Help's margin note, pop-up and hidden text
capabilities, all three outputs can be created from a single
source doeument. There is no need to keep multiple files for
each type of output. And, because Doc-To-Help is a tool that
is layered onto MS Word, there is no need to learn an
additional package; a free evaluation copy of Doc-To-Help is
available at http://www.wextech.com. (I'm not a Doc-to-Help
spokesperson, just reporting the responses.) =^)
* Manual vs. online documentation should be closer in
presentation than the training documentation. Neater things
can be accomplished online.
* Links between .pdf documents can be created using Acrobat
Whew!!! Thanks again for everyone who responded. You've all given me
some very useful information. Now, off I go...