Does Your Documentation Connect the Dots?

The other day I was watching my 5-year old complete a connect-the-dots page. I was amazed at how such a simple concept could turn just about anyone into a semi-functional artist. All he had to do was draw one line at a time between two numbers. At the end he had completed a drawing that would have been far beyond his ability had the dots not been there.

This is exactly how your documentation should be. Software is not art. It isn't golf. It isn't the violin. You shouldn't need to work years and years to master it. There is a task. It needs to be done. People are going to use your software to do it.

Does your documentation allow them to connect the dots?

Now imagine if my 5-year old sat down and saw "1,2,3,4,29". Imagine that between 4 and 29 there are bunch of dots with no numbers on them. What would he do? He would be extremely frustrated. Which dot does he go to next?

You can find these "missing numbers" in documentation all of the time and it creates feelings of extreme angst and frustration - not exactly the experience you are trying to create for your users.

This happens most often when documentation focuses on features and not tasks. Are you telling your user what your program does or are you telling them how to do it?

Next time you are documenting something, ask yourself, am I numbering all of the dots? Are my users going to be able to connect those dots? If not then go back and tidy things up. Your users with thank you for it.