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: 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
educating
> 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
their
> products. They think instructions are the only method to help readers.
Rather
> that explaining WHY the software does what it does, they just document
HOW.
> 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
few
> 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
are
> gamers. Its no wonder they're always calling support. Clearly the tech
writers
> were more concerned with the purity of their FrameMaker template than
actually
> 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
IPCC 01, the IEEE International Professional Communication Conference,
October 24-27, 2001 at historic La Fonda in Santa Fe, New Mexico, USA.
CALL FOR PAPERS OPEN UNTIL MARCH 15. http://ieeepcs.org/2001/
---
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 http://www.raycomm.com/techwhirl/ for more resources and info.
