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:Max Wyss <prodok -at- PRODOK -dot- CH> Date:Wed, 11 Mar 1998 00:27:40 +0100
you do have a very specific use for your documentation. Your product does
limit the user range, therefore you don't have to care about platform
independency. You do however enforce quite a lot of resources on your users
I am not quite sure whether all the features your documentation has can be
implemented with standard PDF, but I think most can with the newest Acrobat
Forms plug-in. With appropriate plug-ins, the rest should be possible (and
then you have the same situation as with your Active-X elements).
I am right now in the finishing stages of a fully interactive electronic
catalog which is PDF based. It allows the user to jump from a given item to
related items (if they are paired) or to the next (wider, longer, bigger,
etc.) item. On the item level, the user has a form which he can use as
worksheet, request for quote, order, etc. This form also allows to enter
customizing requests besides the quantities and delivery dates. The
worksheet can be printed out or be sent as e-mail (if Acrobat Reader runs
under a Web Browser) to my client. My client can use the same set-up for
the quote, order confirmation etc.
So, why was I not chosing HTML for that project? The main reason were
integrity of the documents, platform independency, and interactivity. The
catalog must be an off-line system, running from a CD. Keep in mind that
internet access is still a rather costly business in Switzerland, although
things are improving.
So, I guess, I can say that calling the PDF format "static and
non-interactive" is kind of a myth. But I do agree with you that it depends
a lot on the circumstances, which format is the most suitable for a certain
PRODOK Engineering AG
Technical documentation and translations, Electronic Publishing
CH-8906 Bonstetten, Switzerland
Fax: +41 1 700 20 37
e-mail: mailto:prodok -at- prodok -dot- ch or 100012 -dot- 44 -at- compuserve -dot- com
Bridging the Knowledge Gap
The main reason were control over the appearance (remember, it is a catalog)
>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.
>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.
>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;^)
>> Have fun,
>Michael Wing (mailto:mjwing -at- ingr -dot- com)
>Principal Technical Writer
>Intergraph Corporation; Huntsville, Alabama
>"Humpty was pushed!"