Some criticism of technical documentation

Selena Sol at extropia replies to the question, "What would you want to see in software manuals/technical writing to further disassemble the mystery?" with a thoughtful discussion of what is needed in documentation, "putting the writer back into technical writing".

Being in that field myself, my first thought was that these were pretty basic guidelines -- everyone knows all this by now, yes? On the other hand, consumer complaints continue. I looked around for something recent and technical to evaluate...

Last week I bought a headset phone, for those lengthy conference calls with India late at night. Setting it up and using it was slightly frustrating, but I did get it working. So I took a look at the instruction manual again tonight with my technical writer hat on.

The first section lists all the parts, with illustrations. Nicely done. This is useful. But they flag the battery item with a note: "The battery is located inside the cordless phone battery compartment and must be connected correctly prior to charging." What am I supposed to do with this information right now?

Right after the note begins the second section, "Setting up". Long item for jack requirements and another for installation guidelines. Aha, the next page covers connecting the battery, finally, but there's no task listed for charging the battery. (The content is there, just as a note to "Connecting AC/DC power". This could all be reorganized to be easier to follow.)

So it says not to connect the phone jack until the battery charges for 12 hours. But the step of placing the phone in the base for charging is in the task of "Connecting the telephone line" - so which is it?

Jumping to the next section, I find "Features and Customization". I'd prefer tasks. I understand the procedure for area code selection, but not why I'm selecting an area code. In "Telephone Operation", there are some tasks (making/answering and ending calls, all lumped together) and some features (Ringer Switch, and Call Timer).

So the lesson for me to keep in mind is nicely stated by Sol: "Your readers did not pick up the documentation to learn about the product. They picked it up because they needed to do something with the product."

(Someday I'll blog about exceptions to that...)