Peet Brits

Hmm, but that doesn't make any sense…

Writing IT Documentation

Posted by Peet Brits on November 10, 2009


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.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

 
%d bloggers like this: