Re: HTML vs. PDF vs. HELP

[Jim Gardner <jag -at- RAHUL -dot- NET>]

>Date:    Sat, 9 Aug 1997 14:00:56 GMT
>From:    Stephen Forrest <techwriter -at- IBM -dot- NET>
>Subject: Re: HTML vs. PDF vs. HELP
>
>At 02:00 AM 8/9/97 -0500, you wrote:
>>I am fixin' to start an online procedures manual for my
>>department. I had decided that it would
>>work best as Help, but the more I read about PDF, I wonder
>>whether it is the better
>>choice. One of my associates said he preferred HTML, which I
>>didn't even consider for this project.
>>
>>Other departments might have access to parts of these procedures,
>>and since they might not have
>>a browser or the Reader, I thought Help was appropriate. Maybe
>>there are options I'm not
>>aware of.
>
>Seems to me it depends partly on the method of distribution. If all the
>users are on a network and using Windows, the WinHelp file is easy and
>powerful. They just click on the file and it opens right from the network
>drive. They can even make a desktop icon for it if they want, and they can
>copy it to their own machine if they need to. PDF would also work, and might
>give you some additional formatting options, but each user needs to have the
>browser on their machine. On a network they can download the browser easily
>enough. It's just a couple extra steps. However, WinHelp has some unique
>features that PDF does not have, like pop-ups, macros, and secondary
>windows, so decide whether you want those. Unless you are on an intranet, or
>the users are connecting from far and wide, HTML is probably not the best
>choice, because a series of files is required, and it's slower  to open them
>using a HTML browser. You also lack the unique features of WinHelp.
>

The method of distribution is exactly the salient question. I would only use
HTML if (as it currently stands) if the product is cross-platform. Winhelp
is vastly superior if you are Windows-only. If you have a small Mac audience
along with that there are some workarounds that are admittedly inferior to
Appletalk and such, but minimally acceptable. If UNIX enters the picture you
have to throw out Winhelp options to be sure.

The hypertext functionality of PDF is also quite inferior and a pain to
manage over a long haul without something like Framemaker (where links can
be automagically turned into links within the PDF).Think of PDF as a
pre-press ready electronic print documentation, and you'd be closer to its
real capabilities. As hypertext it is feature-poor.

Developing HTML as a hypertext documentation _system_ is also problematic,
in my experience, as the current development tools are very inferior. I have
been using Robohelp/Word to develop end-user documentation in Winhelp for
several years, and when my company recently barged into the server market I
was forced to develop an HTML system. While I love the web, and in fact my
company is a web-based notification software producer--the tools to produce
HTML are inferior to one used to a bit more control. HTML is great, but you
lose a lot of control you were previously used to having. If it's a small
site that is not a _system_ of interrelated files you can get by. I have
hopes that CSS (style sheets) will revamp HTML to my satisfaction but the
tools are lagging way behind and it will be several years most likely before
any single solution appears. In my experience, since none of the WYSIWYG or
HTML-code editors do the job by themselves, a multi-tool situation that
leads to major stress for the writer is inevitable.

In a recent project, I used the given Robohelp-to-HTML converter but this
only supported HTML 2.0 (no tables). I found myself having to do an enormous
amount of post-processing to fix up the files, and before the project ended
simply abandoned Robohelp entirely in favor of a text editor. The dark ages
are just ahead! :-)

As my company's server projects are forward-looking, I'm still investigating
other options. The Microsoft and Netscape HTML Help formats don't offer much
as they're either ActiveX or browser-dependent. I'm not in a position to
predict or dictate the browser my users will have. Therefore, it has to be
generic HTML.

Also, tools like FrontPage and NetObjects Fusion do a poor job of allowing
one to develop a "hypertext _system_" in the Winhelp sense. For a large
project, you'd want to be able to identify both included files AND name
anchors.

The Robohelp tools also did something incomprehensible. Unlike, Winhelp,
where there's a context identifier (IDH_foo) that doesn't change and
provides a solid marker for context-sensitivity, the Robhohelp conversion
used the Topic Title tag as its identifier. This meant that if I changed a
title the name of the file changed, and as I was calling its URL from the
Java-based server, this became a real pain. If I was working at Blue Sky, I
would've suggested that the user be able to choose a filename instead of
having it tied to the title tag. The tool also produced real ugly file
names, which I'm embarrassed to turn over to our OEM partners, but I don't
have the time to do the SED script or whatever it would take to accurately
replace all the anchors that call those filenames. Ugh!

If anyone is in a similar situation, or differs about the capabilities of
tools I've mentioned....PLEASE PLEASE speak to me! :-)

I'm listening, and really only want to do good work, without major surgery
and worry.

Jim Gardner
FirstFloor Software, Inc.

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html