Documentation is one of the last unconquered areas in software development. The tools tend to get better but the documentation … well, let’s say it could be better. Why?
Part of the problem is that the documentation is written by the developers but the main reason is that they ask the wrong question. They ask “What does it do?” when they should ask “When would I use this?“
Let’s have a look at an example. The OpenOffice help says for “Save”: “Click on Save or press the key combination Ctrl + S. The document will be saved … A file with the same name and path will be overwritten.”
That explains what the function does but not why anyone would use it. How about this: “Save allows you to store the current state of your work as a file in your file system. When you exit the application and start it again, you can load the file and continue where you left off.”
Aha! How about “Copy”?
“Copies the current selection to the clipboard” is boring to write (because it’s so obvious) and doesn’t answer the user’s question. Maybe the boring feeling when you write documentation like that is the nagging suspicion “this is futile”?
Try “The Copy operation allows you to save the current selection in the system’s clipboard from where you can use Paste to insert it in a different place in the same document, in a different document, or even another application if it can do anything useful with the current selection.”
Printing: “Print allows you to send the document to any installed printer. If you install a PDF Converter as a printer, you can make your document available to people who could otherwise not access your work digitally.” Suddenly, the help offers strategies and options.
So next time you document something, ask the right question.
Tagged: Documentation
