Good Documentation – some musings


Warning: Use of undefined constant vs - assumed 'vs' (this will throw an Error in a future version of PHP) in /home/vssrvorg/public_html/wp-content/themes/vs-simplicity/single.php on line 38

Warning: Use of undefined constant simplicity - assumed 'simplicity' (this will throw an Error in a future version of PHP) in /home/vssrvorg/public_html/wp-content/themes/vs-simplicity/single.php on line 38

Warning: A non-numeric value encountered in /home/vssrvorg/public_html/wp-content/themes/vs-simplicity/single.php on line 38

Warning: A non-numeric value encountered in /home/vssrvorg/public_html/wp-content/themes/vs-simplicity/single.php on line 38

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!


Warning: Use of undefined constant vs - assumed 'vs' (this will throw an Error in a future version of PHP) in /home/vssrvorg/public_html/wp-content/themes/vs-simplicity/single.php on line 41

Warning: Use of undefined constant simplicity - assumed 'simplicity' (this will throw an Error in a future version of PHP) in /home/vssrvorg/public_html/wp-content/themes/vs-simplicity/single.php on line 41

Warning: A non-numeric value encountered in /home/vssrvorg/public_html/wp-content/themes/vs-simplicity/single.php on line 41

Warning: A non-numeric value encountered in /home/vssrvorg/public_html/wp-content/themes/vs-simplicity/single.php on line 41

Warning: count(): Parameter must be an array or an object that implements Countable in /home/vssrvorg/public_html/wp-content/themes/vs-simplicity/comments.php on line 33

Warning: count(): Parameter must be an array or an object that implements Countable in /home/vssrvorg/public_html/wp-content/themes/vs-simplicity/comments.php on line 34

Comments are closed.