Friday, June 08, 2007

Bad Documentation

The easiest way to write software documentation is:
Date Field
Enter the date.

Rate Field
Enter the rate.
Needless to say this is very obviously useless. And it's actually worse than useless because any useful information is buried deeply in masses of this garbage. No one would actually write this kind of stuff, would they? Yes, they would and do. And in an amazing example of how we can justify justify anything to ourselves, writers of this kind of documentation actually appear to believe they have produced something useful. (Of course, if someone else had written it, that same person would have no problem recognizing it as useless.)

Of course, it's often thinly disguised. Here are some examples (from real documentation I was given yesterday):
In the Type field, choose the Type this record applies to.

Tab to the Fleet field. Choose the correct Fleet.

Tab to the Abbreviation field and enter the Abbreviation.
I'm sure you get the idea.

The problem is that to write useful documentation is orders of magnitude harder. It requires you to think. You need to decide who the documentation is for, what you hope to achieve with it, what things people need to be told, and just as importantly, what things they do not need to be told.

I think another factor is that people hate to leave "gaps". Rather than just describe the few fields that you actually have something worthwhile to say about, they feel they have to say something about every single field. And this is not just obsessive-compulsive people - almost everyone seems to feel uncomfortable about "leaving out" some fields.

1 comment:

Larry Reid said...

One of the great things about hyperlinking is that you can make everyone happy relatively easily: For the managers who think they're doing the right thing by demanding completeness, you have the "X field: Enter X" type documentation. But then you hyperlink the word "X" to the section that actually describes what the field means in the context of the application.

Unfortunately, to describe what the field means in context would require that the technical writer had the time to actually understand what the application does and who the target audience is. Technical writers are rarely given that luxury.