Good Documentation Tip #3

Textual relationships happen. You meet in some chat room and start typing away. You have so much to share, so much to communicate, but what really matters is the first face-to-face date. Documentation is like that too. All the instructions in the world won’t matter until you actually see what the steps are telling you. The use of graphics and images is vital the creation of good documentation.

Here is an example with tons of information, but does just a textual tease leaving me wanting more.

1. Choose Tools/Macro/Macros
2. Look for a macro named documentname.WriteFrame. Run this macro.

All of it is true and very helpful, but doesn’t give me anything to put it into context. Below I toss in graphics and finally take it to the next level, fully visual.



1. Open document in Visio 2000
2. Select Tools from main menu options
3. Expand Macro
4. Select macros, Macros window opens










15. Select macro name documentname.WriteFrame.
16. Select Run button


Now we’re looking sharp. By adding images we allow the reader to know exactly where they are, what they should be doing & options they have at each step. Gone is the feeling of being lost and bewildered. We finally have instructions that human beings can actually follow. Scandalous.

Practically perfect documentation in everyway.
Tomorrow’s Tip #4 will make it completely perfect.