In Praise of Good Documentation

by Jeremy Jones

OK, this is going to be mostly off-topic for me, but hopefully it'll get a useful point across.

When I arrived at my house last night after the Python meetup, my wife informed me that our washing machine was no longer working. She said that it wasn't spinning and was kind of making a grinding sound. Nice. Not exactly the thing you look forward to hearing when you walk into your home at almost 10PM. I listened to it and validated that my wife's auditory assessment was indeed correct.

She found the owner's manual for the washing machine and I flipped to the troubleshooting section. The manual provided little help beyond making sure the machine was plugged in and the lid was closed. Since it was late, I went to bed with the intentions of waking up early to see if I could figure out what was wrong with it.

First thing this morning, I found an appliance repair website that had a decent troubleshooting section accompanied with detailed instructions for getting at the part which may be faulty. I started dismantling the washing machine per the instructions on the website. Each step was spot on. In 20 minutes, I had sufficiently dismantled the washing machine and located the faulty part. For anyone interested, the coupler opposite the motor was split in half. This explained the grinding sound and the failure to turn the tub or the agitator.

The point is that good documentation can be invaluable. This experience directly translates to having good books on hand for programming, sysadmin, and troubleshooting tasks. In that vain, I can highly recommend Safari. There have been times when I just needed to look something up quickly, didn't want to buy the book, and didn't have time to go to the bookstore and Safari came through nicely.

I know that this is mostly off-topic and fairly obvious. But I think it's an experience (and an application of the experience) worth sharing.


2006-10-17 13:46:52
You know, I like Safari. I just don't care for how it's implemented. IMO, it's too expensive. I would prefer it to be setup like, where you don't have to pay a monthly fee. You create an account w/ a set amount of money and if you print a page or copy some text, then you pay for the privilige. Otherwise just reading the material doesn't cost you anything. Just like a real library.