Over at OpenSource.com, Rich Bowen has a fine article about software documentation.

Have you noticed that the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be? I’ve been contemplating this for years, and have concluded that this is because patience and empathy are the basis of good documentation, much as they are the basis for being a decent person.

Empathy is the ability to understand needs of others so it’s a particularly good trait for someone who’s writing software instructions. This week Your JoeDog was installing a vendor’s code and he ran into a snag with one of the modules. It couldn’t connect to the database and its port listeners were walking on those of another module.

Your JoeDog took the time to detail theses issues so the vendor would have an easy time with his diagnosis. If you construct your prose with the recipient in mind, then you can convey a more meaningful message. That thoughtfulness did make it easy for the vendor to diagnose the problem. Your JoeDog sent him over 1000 words and he replied with a single sentence. That sentence solved his problem while it boiled his blood. And what did the vendor say that caused such a reaction?

“You don’t need to install that.”

“WTMF?” Your JoeDog thought. He omitted MFs from his reply and simply asked the vendor this: “Then why does your documentation tell me to install that?”

“That’s just generic documentation we send to all customers,” he said.

A more empathetic man would have pruned and tailored his documentation to meet the needs of the target audience. Does Your JoeDog consider this man empathetic? No. He thinks he’s kind of a dick.