Good Documentation Tip #1

It’s welling up inside of me, this deep dark hatred for someone else’s documentation. I can feel it creeping up like a bad soup desperate to take flight. I’m trying not to take it personally, but it’s almost as if these people want to be only one’s who can do the task. They are in such fear of being replaced that they write documentation that is illegible by anyone else.

Please people. We can only grow by sharing information. Poorly written specs and documentation will only hurt you in the long run. The next person who reads it will think you’re a dunce who can’t write simple “How To” steps.

Good Documentation Tip #1:

People really do care about the version of software used in documentation. 95% of the problems I see everyday are cuased by documentation leaving out little tidbits of information like that. Take the example shown below.

4.5.1 Create the GIF images
31. Choose File/Save As

What is this step talking about? Where do I choose File/Save As? What software is this step talking about? It makes no sense. Worst part is this is the first step of this group starts with a #31! Does this mean I have to know all about steps 1- 30 to be able to continue? Is that not the very definition of cruel and unusual punishment! Below is my attempt to be less unusual at least.

4.5.1 Creating GIF images in Visio
In Visio 2000
1. Open working file
2. Go to File in top menu
3. Select “Save As”

This is a much better opening step. It tells the reader away what software to be using right away. It also treats the whole step as a group rather then another step in a long list. A person could pick this page alone and still get their work done.

The passionate drama between documentation and myself will continue, but for now I feel I’ve made my point for now. Take the extra steps. You will look less stupid and later readers will worship you from afar.

Look forward to the next thrilling chapter “Good Documentation Tip #2” tomorrow…