RE: Getting rid of the manual

Subject: RE: Getting rid of the manual
From: "Joe Malin" <jmalin -at- tuvox -dot- com>
To: "Keith Hood" <klhra -at- yahoo -dot- com>, "List,Techwriter" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 25 Jul 2006 18:42:14 -0700

No single answer suffices.

At Oracle, all the documentation is online in both PDF and HTML format.
You can get to it even if you're not an Oracle customer! Oracle stopped
printing manuals before I joined, which was nearly 8 years ago.

For some documentation, online manuals are superior. The way Oracle does
them in HTML, you can make bookmarks to a particular section in a
reference manual instead of laboriously writing down that one SQL
statement you always use. True, you can't get to it if your computer is
down. Of course, you can't be using SQL, either!

On the other hand, putting BIOS error codes online has some obvious

Trick question: do you provide a printed operations manual for a
VLSI-processing machine, or do you provide online help? The answer may
be online help: they may not want you to keep printed manuals lying
around in a clean room (or so I've been told).

Do programmers want books? Depends. Learning a language is easier if you
have the book. But remembering the signature of a Java class is easier
if you have context-sensitive online help.

To paraphrase Duke Ellington, there's only two types of documentation:
good documentation, and bad documentation. Good documentation is focused
on the audience and the environment. Bad documentation sometimes follows
the "rules" even if the rules don't make sense.

More trivia: several years ago, the US Navy did a pilot project in which
it replaced all the paper manuals on a destroyer with their electronic
equivalents. They discovered that they had made a net weight savings of
one *ton*. If you were the USN, would you rather shlep around a ton of
paper or a ton of ammunition?

How well does online help work on a cell phone?

FrameMaker has (at last count) several zillion dialog boxes, each having
at least 5 tabs. Why don't any of them have a Help button?


Joe Malin
Technical Writer
jmalin -at- tuvox -dot- com
The views expressed in this document are those of the sender, and do not
necessarily reflect those of TuVox, Inc.

-----Original Message-----
From: techwr-l-bounces+jmalin=tuvox -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+jmalin=tuvox -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf
Of Keith Hood
Sent: Tuesday, July 25, 2006 2:15 PM
To: List,Techwriter
Subject: Re: Getting rid of the manual


WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: Quote marks, cross-references, multiple presentation forms
Next by Author: RE: Survey Question
Previous by Thread: Re: Getting rid of the manual
Next by Thread: Re: Getting rid of the manual

What this post helpful? Share it with friends and colleagues:

Sponsored Ads