Good Documentation – some musings

A ‘speed is better than perfection’ philosophy might be applied to many areas of life, but documentation is not one of them. Unfortunately the standard of documentation needed so that 90% of people can follow it is, well, 90% perfect.

It actually doesnt take all that much longer to write good documentation once you sit back and think for a moment about what it was like when you had to perform the task for the first time yourself. Its no coincidence that much of the better documentation written on this site comes from things the documenter just recently found out how to do.

Documentation doesnt have to be austere, the tone can be warm and conversational, especially if the user is not all that au fait with computers.

However the most important things are still the obvious ones: check after each sentence and see if if you have relayed to the user exactly what he needs to do (and where to find things – screenshots can be of enormous help) and lastly, get your completely computer illiterate auntie/uncle/person-dragged-in-off-the-street to try using your documentation!

Comments are closed.