I image that a fair number of developers dislike documentation. We (developers/coders) hate having to write it, but you probably hate having to make use of poorly written documentation.
Lately, I’ve been on the receiving end of both good and bad documentation and it led me to ask some questions on how documentation is seen and developers attitude towards this often misunderstood but much needed skill.
I believe that one of the reasons that technical documentation is in bad shape is because it isn’t regarded as a skill. Therefore it has not been taught as a skill, it has been relegated to a mere footnote, something worth mentioning but nothing more. In my journey to become a developer no real effort was made by my teachers and mentors to impart the knowledge needed to produce good documentation.
One thing to remember is that documentation is primarily written for someone else and not you. After all, you want your code/component/API to be used right? Documentation provides a bridge that helps whoever wants to make use of your product.
A few key things that documentation does is it
1. Exposes all the features that you have developed for use by other developers.
2. Skilfully guides other developers on how to make use of what you have produced.
3. Reduces frustration towards your product.
Here are some principles I have put together that I think will help change how you as a coder treat the task of documentation.
1. Test the documentation – you test the software before releasing into production, right? Why not test your documentation. Give it to someone else to walk through and check. replicate the steps you have outlined. Get feedback on the gaps and make changes.
2. Iterate – document in stages as you are writing your code. The information is still fresh, also it reduces the probability of rushing through the task at the end of everything.
3. Examples, examples, examples – examples make it easier to follow what needs to be done and reduce confusion and frustration that may arise from doing things incorrectly.
4. Learn – like anything else, take time to actually learn how to write good documentation.
5. Improve – As with all skills make improvements and hone the skill.
6. Teach – Teach others what you have learnt either by verbal communication or writing a guide on how to produce good documentation.
My sincere hope is that over time I will have less encounters with documentation that makes me weak, lol. I’ll certainly do better with the documentation that I produce, and I’ll do my part in teaching other developers what I have learnt.