Did you know there is a specific “computing” definition for the term “documentation”? I never really thought about looking it up – until I decided to write about this topic.
1. the use of documentary evidence.
2. a furnishing with documents, as to substantiate a claim or the data in a book or article.
3. Computers. manuals, listings, diagrams, and other hard- or soft-copy written and graphic materials that describe the use, operation, maintenance, or design of software or hardware: The documentation for the driver program is displayed on the screen.
Then, I had to laugh out loud when I read this example sentence used in the online Merriam-Webster entry: The program’s documentation was poorly written.
After my initial laughter, I was saddened that that sentence was considered a good example of how to use the word. Why couldn’t it read “The documentation provided all the steps required to successfully complete the task.”? Isn’t that the goal in providing documentation? For many of us, documentation is the main output of our role. How short we all must frequently fall for that to be an example sentence!
How can we improve our documentation so that it is not described as “poorly written”? I think it is like the three rules of real estate – location, location, location; but my three rules of successful documentation are: review, review, review… and maybe even a fourth review.
Self-review is difficult; you have a built-in bias and it is difficult to be objective with your own work. Considering you wrote the document, you know what you intended for it to accomplish, and it made sense at the time you wrote it. Therefore, write it, and put it away for a few days. Then come back to it and see if it still makes sense. I guarantee after letting it sit for a while – you’ll find ways to improve it when you review.
Next, have a colleague review your documentation and provide constructive feedback. This can be difficult as we must be open to accepting criticism of our work and then try not to take that criticism personally. We should remember that at the end of the day we don’t want a picture of our document next to the “poorly written” example sentence in the dictionary entry! So, keep an open mind and be sincere when asking the reviewer for suggestions to improve the document.
This review should be performed by a member of the intended audience for the document. Similar to the peer review – ask the user to provide constructive feedback on how to improve the document to ensure that they are able to use it effectively and that it actually helps them in their job. What outstanding questions do they have about the process that the document still needs to address or clarify?
The final review – and perhaps this one is done before the user review depending upon your situation – is to give the document to someone outside the intended audience. Try to find someone who will not get caught up in the actual technology, but can provide feedback on general document flow and content. Sometimes this review can provide the most benefit in identifying documentation gaps exactly because they don’t know the technology. This reviewer will often help to identify the “intuitive” steps which may have been left out when they ask you to clarify exactly how you got from point A to point B.
Thanks to my mom for reviewing this post for me and providing constructive feedback!