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:Re: Cross-Platform Help From:Gary Merrill <sasghm -at- UNX -dot- SAS -dot- COM> Date:Fri, 8 Dec 1995 18:35:13 GMT
In article <H000058a0380d9da -at- MHS>, Caryn Rizell
<CARYN_RIZELL -at- hp-roseville-om2 -dot- om -dot- hp -dot- com> writes:
|> I was intrigued by your comments about HTML. Why don't you like it as a
|> help system? My group is looking into producing our online as HTML, so I
|> would welcome any feedback you have on why not to do it.
I got email from Caryn before I saw that it had also been posted
here. Below is most of my response to her.
There are a number of issues here. I may not even recall all of them
at the moment, but for starters ...
1. HTML is a seriously impoverished language for doing any
decent kind of formatting and display. You don't have
to use it for very long before you discover that there
are just a lot of things that you would like to do that
you can't. For example, tables. I'm currently in the
process of creating a module (part of a compiler) that
will generate a documentation file in HTML for the
source code being compiled. It would be really nice
to have some of it in tabular form. But no. Yes,
I know tables are in HTML/3. But that isn't here yet
and isn't likely to be for some time. And I know that
Netscape supports table extensions to the language,
but not everyone has Netscape. Then there are a lot
of other things as well. How about something as simple
as hanging indents? Etc. HTML was designed as a
very *simple* language to support *information retrieval*
over wide area networks. For that, it is okay. For
anything that is supposed to be really interactive,
2. What do you use for a viewer? Mosaic? Netscape?
You really want each of your help dialogs to be
decorated with all the crap on those windows? It
has nothing to do with the application, can be
confusing to users, and takes up screen real
estate. (For this reason I'm doing my own
viewer(s) for applications in which we wish to
3. Display of HTML tends to be quite slow. In large
part this is because of the model on which HTML
is based: everything is in a separate file and
each such file has to be accessed when a link
is triggered to it -- frequently across a network.
I find using help implemented in this manner to
be frustrating and tedious.
4. The document model (see 3) for which HTML was designed
is *not* the model you want for a high quality help
system. Every HTML file is a separate flat representation
of the text. It cannot be separated into sections or
pages. You end up with either one large file or you
have to split things up into individual files with
resulting performance degradation. You cannot implement
a glossary in a decent way in HTML. It would have to be
a separate file that is linked to, and you would have
to carefully manage all of the links and anchors
yourself. There are no glossary tags in HTML. Similarly
for a keyword index. Similarly for an index in general.
5. What about popups? These are extremely handy in a
help system and can greatly enhance its useability.
In HTML, forget it.
Some of the problems in using HTML for a help system
are problems with the viewer rather than problems
with HTML itself. These could be overcome if you
can provide a better viewer to your users. But
most people simply use Mosaic. Other problems are
simply a result of the fact that HTML was not
designed with the idea of supporting a sometimes
complex interactive environment of the kind that
is needed for a quality help system.
I have a tool that I wrote and maintain for the use of
SAS developers. Xcmp is a sophisticated side-by-side
text file comparator. I wrote the help for it in
the HP Help System. This is actually similar to HTML
in being a tag-oriented language (another SGML
DTD, I'm sure), but it has a number of features
designed specifically for a help system: glossary
tags, index tags, a really nice viewer, popups
(at least to some degree, though not as straightforward
as one would like), and the capability of easily
spawning other processes from within your help
file. In fact, it is straightforward to write
sophisticated interactive tutorials with this
system. It is much better than HTML, but I still
do not regard it as a *good* help system.
The Xcmp tool is used very heavily by software developers,
but has also acquired an enthusiastic following among
translators in europe and Japan. Not all of those
users have the HP Help System installed on their
machines (it's an extra cost option). For them, I
have an HTML version of the help. It is the same
text, the same content. But compared to the HP
version it is truly second rate. It is slower,
more difficult to use, and simply does not look
as nice. If you want a *quality* help system,
avoid HTML. The *only* advantage of HTML currently
is portability. I do not regard this as a significant
payoff when compared to overall quality. We have
heard that the help system for the Common Desktop
Environment (CDE) is the HP Help System, but somehow
based on HTML. I do not know the details of this and
have not seen examples of it running.
The one thing you need to impress upon people (as
I'm sure you know) is that help is not just on-line
documentation. The structure of a good help
implementation is significantly different from
the structure of a paper manual or on-line manual.
(This is one reason that the SGML ideology of
"single source" is a crock.) HTML will give you
a simple "lowest common denominator" kind of help.
And it will give you portability to a variety of
systems. But it won't give you a quality product.
Gary H. Merrill [Principal Systems Developer, Compiler and Tools Division]
SAS Institute Inc. / SAS Campus Dr. / Cary, NC 27513 / (919) 677-8000
sasghm -at- theseus -dot- unx -dot- sas -dot- com ... !mcnc!sas!sasghm