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: Re: Should we skip HTML? From:"Wing, Michael J" <mjwing -at- INGR -dot- COM> Date:Tue, 10 Mar 1998 13:36:54 -0600
> I find Acrobat to be faster and easier than a web browser for local file
> access. It also consumes far less memory than the browsers I keep around.
> In addition, it's far more stable. Give me a choice for viewing a local
> and I'll take PDF every time.
I guess that I must be using HTML differently than most. In my case, it's
not so much the integrity of appearance than it is functionality and the
ability to interact with the reader that drives my choice. My project is
delivered as a directory of local HTML (not HTMLhelp) and GIF files. Size
does not seem to be a problem. The entire project (300 pages printed,
graphics, and automation code) zips to 700K (1/2 a floppy). Formatting is
somewhat mutable. The reader can set their own fonts and sizes. Styles
control non-breaking paragraphs, positioning, and so forth.
I am using HTML because my product (an automation programmer's guide to our
application) is as much an application itself as it is a document. I am
making liberal use of dynamic HTML features and I am also automating the
product through the document (by using VBScript).
I need the scripting to do "Show Me(s)" for the code. My examples are
interactive. I actually use the HTML document as a custom-designed interface
to the application (creating custom interfaces, is what the document is
teaching them to do). For example, part of the automation retrieves
geographic data from a database and displays it in a window. I provide the
description and example code for automating this process. However, I also
put the controls (buttons, text boxes, and so on) in the HTML document that
allow the user to select the database, the features, and the symbolization
characteristics. There selections are applied to the automation code as
shown in the example. I automate the controls to drive the application
through these controls using the script. The controls also allow the reader
to see the effects that changing automation values has on the data.
Therefore, PDF, WinHelp, and printed documents are out of the question for
As another example, I also have put check box controls in the descriptions
which allow the reader to hide or display code descriptions. Therefore,
they can read the example code uninterrupted or read it with explanations
interspersed with the code. To the best of my knowledge, I can't do this
(let alone drive the application) with PDF.
> The only time I miss the control a browser gives me over the page is when
> encounter a bad design. And I encounter bad design far more often in HTML
> than in PDF. I don't want to spend my time tweaking your design to make it
> usable. I want to read it and be done with it.
In my case, the interaction with the document is regulated to IE4. I do a
version detection on the load of each page and preface each script with an
"If browser is IE4 then execute script; otherwise, display message saying
IE4 is required" -type condition. However, we redistribute IE4 on our
product CD and the browser built into the application uses the IE4 ocx. If
the user does not view my document on IE4, the text and illustrations are
static, the context-sensitive help calls do execute, and the interactive
controls are ignored by the scripts. Also, the "On Error Resume Next"
statement suppresses the error messages should a combination of events cause
the wrong browser to start a script.
> PDF excels at keeping things simple, at presenting the information cleanly
> and clearly. HTML, using any realistic number of illustrations, will
> in many small files, which given the cluster sizes on most people's hard
> drives today, will waste a ton of disc space. (Not to mention that a user
> seems far more likely, in my experience, to blow away or otherwise mangle
> one or more small files than a single big one.)
Like others have stated, if the document is static and non-interactive, and
if preserving formatting, and so forth are requisite, PDF is fine. In fact,
I like the combination of an HTML page linking to PDF documents. If,
however, the document is more than just something to be read, HTML wins
Our users have the option to keep the HTML files on CD. They can't blow
them away. If they corrupt the copied files, they just reload.
> To my mind, HTML over the net is useful; local HTML files mean a lazy
Again, this depends on the intended use of the document. Something about
choosing the right tool for the right job. Besides, my DHTML designs have
plenty of energy even when I don't;^)