Good Documentation Tip #4

Problems happen. No matter how much you try to plan ahead or how carefully you read the directions, random stuff just goes awry. This is one of the painful facts of life. As soon as you take the time to write out clear, honestly and visually helpful directions, issues will pop up that we have no control over.

Now that we know these little annoying misshapen happen, what are we going to do about it? Are we going to make up possible excuses and then hide them at the end? No! We’re going to put them right where the problem could happen & where the reader will need the answer.

My example from yesterday is a simple draft of good documentation rules, but it doesn’t take into account a major issue for readers. Below I add in that one last finishing touch needed. The reader now has complete instructions for the task at hand.


17. Select macro name documentname.WriteFrame.
18. Select Run button

Troubleshooting: If the macro documentname.WriteFrame is not immediately visible, open template Framework.vsd located in server/templates/Framework.vsd and continue work from there.

If macro is still not present, see your local administrator.


By troubleshooting at a step level you remove the effort readers go through when things go wrong. Keep it in the moment and with the context required to complete the task at hand. Remember, problems happen. It’s how and when you handle them that count.

Drop in tomorrow for the chilling conclusion of Good Documentation Tips…