User vs. technical docs: style difference?

["Geoff Hart (by way of \"Eric J. Ray\" <ejray -at- raycomm -dot- com>)" <ght -at- MTL -dot- FERIC -dot- CA>]

Lisa Comeau is <<...compiling things like FAQs, and step-by-step docs
for users. Our Documentation Standards Committee has a totally
different way of doing this which is geared toward the technician...
I say that documentation for the average end-user MUST be written
differently (in tone, format, writing style) than that for
technicians.>>

This is one of those techwhirler rules of thumb that seems so obvious
that there could be no possible need of "proving" it... until it
comes time to prove it and you suddenly realize that you've never
mustered any proof. Fortunately, the proof is quite simple and relies
on examples. First, head down to your library and check out a
technical maintenance manual for your car (you know the type: the
ones intended for home hobbyists that tell you how to be your own
mechanic). Second, head down to your car and pull out the owner's
manual. Ask the manager to use the technical manual to find
information on how to steer the car and brake safely in inclement
weather; someone might be able to do it, but it'll take a bit of
work. Then supply the owner manual and ask how to replace a
defective radiator. That should make the point quite clearly, unless
the manager also happens to be a car-repair buff; if you suspect
that's the case, pick another example (e.g., the Reader's Digest home
guide to family health vs. the Merck manual). If all else fails,
find a contract full of legal jargon and ask the manager to explain
it: "After all, you're bright enough to understand all this
technobabble, so surely you can figure out a harmless little
contract?"
--Geoff Hart @8^{)}     Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Patience comes to those who wait."--Anon.


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=