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: Online Documentation. New! Improved! From:"Wing, Michael J" <mjwing -at- INGR -dot- COM> Date:Thu, 17 Oct 1996 11:52:28 -0500
>>Online may not be a 'real' manual, but it is a 'real' document and its
>>acceptance/usage is growing 'real' fast.
>The problem is not that it's impossible to do good on-line documentation,
>but that the flagship products have garbage-scow documentation, and
>many people cheerfully salute the flag and emulate the garbage scow.
Then by this logic --> Document is poor. Document is online. Therefore
online is a poor documentation medium.
A tool is a tool. Online documentation presents many new and expanding
possibilities. One being an interactive learning environment. Another
being instant cross-referencing. A third, automatic detection of
application configuration, and thus presentation of only the
documentation pertinent to the configuration and software in use.
Whether the actual use of the tool has produced 'garbage scow' or a
masterpiece is a product of the person, not the tool. Don't scrap the
electric screwdriver for the manual one because the carpenter never
plugged the electric one in.
There may be a number of not-so-great online documents now. Especially
since much of the territory is new and changing. Saying it only
produces 'garbage scow' and 'is disgusting' comes across as 'Man will
never fly' remarks.
>Sure, you can do really cool on-line documentation. But it's a
>fallacy that on-line documentation is all that different from any
>other kind of documentation. It has the same goals, the same
>subject matter, and the same readers as a paper manual would have.
But it has expanded capabilities in presentation. Can a printed
document launch/manipulate an application (let alone with customized
parameter settings)? Can a printed document embed and activate a video
or audio presentation? Can a printed document automatically ignore
topics/chapters that are not part of your configuration? Can a printed
document automatically open to the correct chapter/topic? Can a printed
document respond to user input?
>Many people, though, have fallen for the line that on-line documentation
>is somehow very different -- that the fact that it is on-line changes
>the nature of the information that people need to use the product.
Not the nature of the information -- the method in which the information
is presented, disseminated, and obtained. Classrooms used to use
granite slates and chalk, then overhead projectors, and now computer
displays. The nature of '2+2 = 4' or 'Press the Start button' has not
changed, but the medium of presenting the information has.
>Specifically, products that always shipped with heavy and expensive
>paper reference manuals sometimes appear with on-line-only documentation
>-- and no reference manual.
There are such things as online reference manuals (I write some of
>The assumption seems to be that the switch from paper documentation to
>on-line documentation actually makes the users stupid.
An assumption mostly made by writers who resist any mention of going to
>Of course, not everyone falls for this piece of idiocy, but I'm AMAZED
>at the number of programs in whichI have where the documentation has sunk
>to the duh-level -- where every self-explanatory button and field is
>explained in massive detail, but there's no hint as to what happens when
>you press the "OK" button.
Two things here. 1) The 'duh' factor may be part of better designed
interfaces. A well designed interface should have a great 'duh' factor.
If the button is 'self-explanatory' it means that the interface is
intuitive (almost not needing documentation).
2) The documentation for 'what happens when you press OK' did not get
erased because the document is online. This, again, is a product of the
writer not the tools. Missing, incomplete, or inaccurate information is
not analogous to the medium in which it is presented.
>For example, just TRY to find an explanation of QuickBooks' approach to
>basic accounting practices in the documentation. It doesn't exist.
>There's a duh-level explanation of the difference between cash and
>accrual methods, but there's nothing to indicate which of the many
>variants in accounting practices QuickBooks uses internally.
So you have a poor online document. So what! Does that mean --
Quick Book's online document is bad, ergo, all online documents are bad.
>On-line help can be seriously cool, but at the moment most of it is at
>a stage marked by the confluence of the "non-writers reinventing writing
>in a vacuum" and "Wow!
What a broad and inaccurate generalization. This presumption appears to
Writers write printed manuals - online is not a printed manual -
Therefore, online documents are not written by Writers.
This argument could have been used to resist and denounce the typewriter
some years back.
>Look how many buttons, balloons, sound bites,
>pictures, and hyperlinks I can cram into this paragraph!" phase --
>much as desktop publishing was ten years ago.
Look at how many pages I can cram into the binder -- must be a great
manual! Look at all the screen shots. Here's a screen shot of a
50-field dialog box. Here's a screen shot of the same dialog box with
field 1 completed. Here's a shot with fields 1 and 2 filled in. And so
forth. Hey, here's a table telling the page and page number of every
procedure in this 10,000 page manual. Here's the same table put in page
order; another in alphabetical order. Here's a table listing the page
number of every other table in the manual.
Wait a minute, here's another complete set of manuals for a slightly
different version of the product. Most of the information is exactly
the same but it was put into separate documents because the instructions
got two confusing as to which to use for which version and/or which
steps applied to which version.
The 'cramming of buttons, balloons, and so forth' sounds like
technophobia. Aren't you the guy who constantly puts down Engineers and
>Some of it is growing pains, but much is useless noise caused by people
>emulating "market leaders" instead of figuring out what's what.
Then master the technology, ignore it in whole, or become a market
_/ Michael Wing
_/ Principal Technical Writer
_/ Infrastructure Technical Information Development
_/ Intergraph Corporation
_/ Huntsville, Alabama
_/ (205) 730-7250
_/ mjwing -at- ingr -dot- com