RE: Advocating Documentation and Support

Subject: RE: Advocating Documentation and Support
From: Tom Johnson <johnsont -at- starcutter -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 8 Mar 2001 15:00:11 -0500

On Thursday, March 08, 2001 1:42 PM, Andrew Plato
[SMTP:intrepid_es -at- yahoo -dot- com] wrote:
> What is says is that too many documents instruct readers rather than
> them. I can't tell you how many manuals I read that are just non-stop
lists of
> instructions. There is little if any context to those instructions.
> I think this is the outcome of documentation teams that do not understand
> products. They think instructions are the only method to help readers.
> that explaining WHY the software does what it does, they just document
> Point here, click there, enter your name, hit OK, thanks for buying our
> product, here's our web address, the end.

You are right; to a degree. Tons of manuals are as you describe. That
doesn't mean they are ineffective. Some people require that very approach.
Some products require theory, some require the "Button-pusher's guide to
Xproduct." You mentioned bulldozers. I don't know for sure, but I doubt the
manual for a Caterpillar D-9 goes much into theory about how to use the
product. It probably says, here is the clutch, here are the brakes, don't
put gas in the diesel fuel tank.

Those that right manuals on network security should discuss theory. Each
product requires a careful evaluation about how to present the information.
Sometimes this might require multiple documents using different approaches.

> I've read probably every network security product manual out there. Very
> of them describe what to do if you're playing an on-line game like Quake
III or
> Half-Life. DUH. Probably 75% of the users of network security products
> gamers. Its no wonder they're always calling support. Clearly the tech
> were more concerned with the purity of their FrameMaker template than
> paying attention to the needs of the users.
Yes, people like Frame and they like templates, that doesn't mean templates
are always used at the expense of the users' needs. I've said it before
and I'll say it again. Frame saves me countless hours compared to Word. I
use Word a lot and know it almost as well as I do Frame (been using it for
12 years now). As far as manuals are concerned, Frame really frees up my
time to do other things like talk to SME's. That way I can spend the time
on content, even if it doesn't have much theory. I really don't need to
explain to a toolmaker why too much radial land is a bad thing on an
endmill. He already knows that, I just need to tell him how to reduce it.

Tom Johnson
Technical Writer
Elk Rapids Engineering Div., Star Cutter Company

johnsont -at- starcutter -dot- com - work
thomasj -at- freeway -dot- net - personal


Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**New Dates!!** San Francisco (Apr 16-17), San Jose (Mar 29-30) or 800-646-9989.

IPCC 01, the IEEE International Professional Communication Conference,
October 24-27, 2001 at historic La Fonda in Santa Fe, New Mexico, USA.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: Ruffled Feathers
Next by Author: RE: Converting AutoCad Drawings
Previous by Thread: RE: Advocating Documentation and Support
Next by Thread: RE: Advocating Documentation and Support

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

Sponsored Ads

Sponsored Ads