Re: encouraging learning by experimentation?

["Gary S. Callison" <huey -at- interaccess -dot- com>]

"Jo Francis Byrd" <jbyrd -at- byrdwrites -dot- com> wrote:
> We write the user's guides with the bare minimum of information for a

who 'we', paleface?    ;-) 

> complex application. Then some expert comes along and writes the
> "Bible" for said application, explaining all the fine tuning and
> nuances and makes a fortune.
> How many of us invest in third party books so we can get a thorough
> understanding of the application?

I can't be minimalist, I can only provide both a quick-reference guide
for those who don't need the big picture, and a complete manual for
everybody else. If I omit anything, the helpdesk gets irate phone
calls. There is no 'expert' who will come along and write the bible for
these applications. It's all me.

And, I _like_ it this way. 

I have a 1990 Plymouth Laser, with a bad washer pump. The owners manual is
useless. The Haynes book (there's your 'experts', har har) does not
acknowledge the existance of a washer pump. The instructions that come
with the washer pump have helpful instructions like: 
1. Disconnect wiring and hoses from washer solvent bottle.
2. Remove washer solvent bottle. 
3. Gently pry old pump from bottle.
4. Install new gasket.
5. Install new pump in bottle.
6. Replace bottle in vehicle. 
7. Reconnect wiring. 

Now, those directions are useless. Anybody buying the damn thing knows
that much. Here's what it SHOULD have said. 

1. When you park the car, turn the wheels to the right, so they're out of
   the way when you remove the trim panel from in front of the drivers-
   side front wheel. 
2. Chock the back wheels, jack the car, and support it with jackstands.
3. Unless you have hands like an exceptionally dextrous young spider
   monkey, remove the two bolts holding the power steering fluid
   resevoir. The bolts are 12mm. 
4. Disconnect wiring and hoses from washer solvent bottle. Imagine
   yourself attempting this with the power steering thing in the way. 
5. Remove trim panel in front of driver's side front wheel. There are 
   five expansion-type trim clips: three on the outside of the wheel well,
   and two at the bottom of the panel close to the transaxle. These 
   trim clips come off by loosening them with a phillips screwdriver, and 
   then prying the base out with a flat-head. At the top of this panel, 
   there should also be two bolts (or self-tapping sheetmetal screws 
   if the previous owner of your car broke the bolts off and didn't 
   think to tap those out and replace them correctly) you must remove.
6. With that out of the way, you can now easily remove the bottle.
   There's three bolts holding the bottle in: one at the bottom left, 
   one at the top right, and one on a bracket that bolts to the underside
   of the top of the wheel well. These are 10mm, and you'll need a 6"
   extension for the top two.
7. As you're looking up from under the car, the bottle will snake out 
   if you move the bottom towards the back of the car and rotate the 
   neck about thirty degrees counterclockwise. 
8. If the bottle isn't empty and you're into recycling, find something
   clean that can hold a half-gallon or so of liquid, and dump the 
   bottle out into it.
...

3. Gently pry old pump from bottle. 

So, while I see the point of minimalism, in this particular instance, the
first two instructions could easily pad out to a page. That's a little
much to expect from the sheet of paper that comes with the washer pump -
but not the Haynes manual. 

Of course, after my new-and-improved first page of the instructions, you
could always include my personal favorite gem from tech writing in the
automotive industry, "Installation is the reverse of removal". Someday,
I will find the person who writes this, and kill them, many many times.
If the original author of this phrase is dead, I will dig them up and
kill them again. While technically accurate and wonderfully minimalist,
this is about the most useless bit of instruction you could ever give. I
don't think there's a single piece of technical writing that annoys me more.

-- 
Huey



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l

Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

---
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.