Re: Cross-Platform Help

[Gary Merrill <sasghm -at- UNX -dot- SAS -dot- COM>]

In article <H000058a0380d9da -at- MHS>, Caryn Rizell
<CARYN_RIZELL -at- hp-roseville-om2 -dot- om -dot- hp -dot- com> writes:
|> Gary:
|>
|> 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.
|>
|> Thanks

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,
   forget it.

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
   display HTML.)

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