How many programmers would agree that there is a lot of useless IT documentation out there, mostly because they state the obvious. Microsoft documentation is often very guilty of this. For example, is the phrase “creates a new XML Node” really a good definition for “XmlNode”?
I am not here to rand and rave about problems, but rather to suggest possible solutions. There is a long forgotten rule that I would like to point out:
Rule: Do not use the defined word inside its definition.
Most definitions stating the obvious is guilty of breaking this rule. Let me go back to my “XmlNode” example from earlier. Instead of stating the obvious, which everybody already knows, most people reading the documentation would probably want to know the difference between “XmlNode” and “XmlElement”. Here is a hint for applying the rule: Begin your sentence with “An XmlNode is a <…>”.
I know most programmers would rather eat their hat than write documentation, but when you absolutely have to do something, at least do a decent job at it! I hope this post will set the right mindset for writing better documentation.
Peet Brits 