Have you ever been using a high tech product or software application, and ran across a command or prompt which you did not know, went to the help, and found a help entry, but that entry actually tells you nothing? For example, you see a menu called “XXX” and you wonder what it does, so you go to the help or the manual, and look it up. The entry says (and I quote) “In order to XXX select the XXX Menu.” This is Content Free Documentation.

CFD is caused by “Documentation Standards”. Someone writes a rule that says something like: every menu item should have a corresponding help entry. This gets assigned to documentors who were probably given too little time to complete the job, or else had to deal with many last minute changes, or possibly were not even trained writers at but instead were aspiring actors who managed to land a tech writer position as a day job. Whatever the reason, they mechanically worked through the program, and fulfilled that rule that every menu item should have documentation. Here is an actual example:

You have a check box which is labelled “Enable Autoplay for CD and DVD Drives”. At this point, there are basically two possibilities. Either the user understands this phrase or does not. If the user understands the prompt, then the user is not going to need to read any further document. Yes, Sherlock, this means that the description is really for those users that do NOT understand the prompt. There are a number of reasons why the user might not understand it: The user might not know what “Autoplay” does — I know it seems obvious, but there is the possibility that the user has no experience with this and really is not sure what this means. The user might not know what CD drives and DVD drives are. Or there might be questions about the entire context, for example when does “Autoplay” get activated and at what time will this setting take effect.

But our faithful tech-writer did not waste time with any of these possibilities. Apparently the writer thought that if a user does not know what to do here, simply repeating things a few times might work better! This is right along the line of thinking that if this foreign person can not understand English, it might help if I simply yell it a little louder in English. I am rather surprised that the description is not in bold, or at least a larger font.

Lets do a little bit of “information analysis” on the description. We know that the user who needs the documentation does not understand the phrase “Enable Autoplay for CD and DVD Drives”, so including that in the description adds no information value. So let’s remove that phrase from the description, and see what is left:

Check “” to

There we go, an excellent example of Content Free Documentation.

Perhaps you think I exaggerate a bit. It is possible that the technical writer thought that user might not know that the little square box is in fact a “check-box” and so was informing the reader that the box can be checked. Ah-ha, some information, you think? No, I am afraid not. Because, if the user does not know that the box is a “check-box”, then the verb “to check” has no meaning to the user. The verb “to check” might be interpreted to “read the sentence again to make sure it is correct”. Once the user has completely and thoroughly checked the prompt, it would still have no meaning for him.

CFD exists everywhere, particularly in help files and software documentation. What is the harm? It wastes time, and people don’t like that. Imagine you are that person who does not understand the prompt. Sometimes you have to open a help window, and hunt through pages of poorly organized text in order to find the help that is relevant to your prompt. If at that time, you find that the help is a phrase that consists only of a repeat of the original prompt, it is quite a disappointment. IT would be better if there was no help at all. As Tom Lehrer said: “People who have nothing to say should at least have the decency to shut up.”

What can be done about it. Well, the rule should be simply: if the documentation does not add any substance that can not be gleaned by a looking at the subject of the documentation, then there should be no documentation. Or better: documentation should contain some phrase or description that could not be picked up simply by looking at the page. People are looking to the documentation because they don’t understand the prompt, the very least the documentation should do is to phrase the information differently in case it is simply the wording that is confusing.

I started looking around for example to include in this post. I am using FireFox just now, so I when to the “options” menu. At some point it says: “You can also click the Check Now button to do a check right now.” Yes this is a direct quote! How about something like “You can also click the Check Now button if you don’t want to wait until the next time Firefox is started.” That actually tells you something you don’t already know.

My experience is that you can find CFD almost anywhere you look for it in modern software. Let me close this post with a simple plea for the technical writers of the world:

Users come to your document to learn something that they do not already know. Please ALWAYS include something in your writing that the user could not pick up by simply looking around at their environment.

And by corollary:

If you can’t think of anything that the user does not already know, then please leave the page blank.