Characteristics of Good Documentation
As a developer, reading documentation is one of the most important aspects of learning a new technology. If you’ve ever written any code in your life, even “Hello, World”, you have likely come across documentation. Whether it was good documentation or bad is entirely up to you, the reader. What I aim to do in this post is to clarify what I, personally, look for in order to classify a document as “good documentation”. Ready? Let’s go.
Good Documentation is Up to Date.
There is nothing more frustrating than getting excited about beginning a new quest in learning something new only to find out the manual describes how and what to do in older versions, but not the current one. Before a product or project is released, the documentation should be modified to reflect the changes as necessary.
Good Documentation anticipates failure. Lots of failure.
When learning a new technology, many people don’t start with the documentation, but rather, end up looking at the documentation once they’ve hit a road bump. Documentation that anticipates this road bump will be extremely helpful to newcomers. When creating the documentation, try and think of ways the user could screw up (which, by the way, they will. Always).
