The unsung hero of productivity: Why you should make good documentation a habit

“This is the code of the middleware system that you must work on. The person developing it did not have time to do any documentation, so you need to figure out how the thing works. I hope that should not be too difficult.”

This is a paraphrasing of a conversation with my supervisor during the beginning of my doctoral thesis at university. I remember thinking at that point – it’s just code, how hard could it be to go through and understand it? However, it was an extremely time consuming and laborious task. In retrospect, had some form of documentation been available, the time spent understanding the code could have been better used for my research. It was then that the importance of documentation dawned on me.

What defines good documentation?

The term ‘documentation’ can have multiple meanings, so it is important to clarify what it stands for in the context of this article. Within the purview of this article, documentation refers to technical manuals or guides and general technical articles. So, the question that arises now is – what is good quality documentation and why is it important?

Good documentation can be characterized by some of the following attributes:

• Easy to understand
• Simple to follow along and written to the point
• Understands the target audience and their knowledge level
• Updated regularly to reflect the latest trends and techniques
• Checked thoroughly for errors and typos

The importance of documentation from a reader’s perspective is quite intuitive. The presence of well-written documentation makes the learning process for new software/technology faster and efficient. Drawing upon my example earlier, having quality documentation readily available makes the learning curve shorter and frees up time to experiment with the relevant technology. Good documentation also contributes towards increasing productivity and faster troubleshooting of problems. As an end user, good documentation is a key enabler for the faster adoption and use of software/technologies.

Why put in the effort to create good documentation?

Because it is the ‘write’ thing to do!!

Ignoring that terrible pun, when it comes to the perspective of the person creating the documentation, its importance may not be so obvious. The process of documentation is usually a time-consuming job with no immediate incentives. Especially if documentation is not part of one’s primary job description, it is easy to overlook it. As an engineer, one might have the impression that their work is limited to developing software and making the effort to create quality documentation for it is just an extra add-on to be done if time permits.  This mostly holds true for people who are not directly involved in developing software and products that are to be used by the end consumers.

So, why should we strive to create and maintain good quality documentation? Well, documentation in any form is a good tool to spread knowledge and make other people aware of what you have been working on. In an organization like Axis with multiple departments, having well written documentation is instrumental in finding out what is happening elsewhere. There is a fair chance that the problem you are working on is being looked at from another angle in a different department. This could then pave the way for further collaborative work.

Even if we keep the benefits of documentation from a collaborative point of view aside, it is also beneficial for one’s own personal development. When you put down your experience of working with something in the written form, it helps in clearing your own understanding as well. To cite an example, as part of our work in Core Technologies Systems, we have often worked with integrating existing open-source tools with Axis devices. This sometimes involves making some specific configuration changes to those tools so they can work seamlessly with the Axis devices.

We have adopted the practice of transforming these experiences into technical guides so they can be followed by people who are interested in trying out these things. We have observed that this simple practice of documenting has contributed to a clearer understanding of the problem. Further, since the information is retained in the written form, we can refer to it in the future when needed without wasting time shuffling through old notes.

Another interesting benefit of getting into the practice of documentation is that it could become your first step towards becoming an open-source contributor. When we think about contributing to open-source, code contributions are the first things that spring to mind. However, contributing to open-source documentation is also a good way to give back to the open-source community.

Also, contributing to documentation might be an easier way to familiarize yourself with the whole process of submitting proposed changes to open-source and going through reviews before those changes are merged. I have had the opportunity to propose some corrections and improvements to some of the installation guides of the open-source tools we have been investigating and these changes have now been incorporated. This process increased my confidence and inspired me to make further open-source contributions.

How to make documentation a habit?

The importance of having good documentation both from the perspective of the writer and the consumer has been established in the preceding paragraphs. So, how do we create an environment where good documentation is the norm and not the exception? These are some of the suggestions that come to mind based on my experiences within our team:

• Include documentation as deliverables – The project order formally lists out the different documentation that would need to be generated as part of the project. By including the documentation as deliverables, the time and effort needed to generate it is factored and budgeted into the project scope.
• Work on documentation continuously –Instead of relegating documentation to the project end phase, we try to do it throughout the project. Whenever an internal project milestone is reached, relevant documentation in the form of guides or articles is written down. These practices ensure that the process of documentation is integrated more tightly with the project life cycle.
• Carry out periodic reviews of the documentation – Documentation is of good value only if it is reviewed and updated regularly, especially in a fast-moving technical landscape that we are a part of. We usually have internal documentation reviews within the project groups where we read and offer feedback. In the case of technical guides and manuals, we try out the steps outlined in them and provide feedback to the writer in case of any confusion. This process ensures that the guides are ready to be used and followed by readers.  We conduct a documentation review with those commissioning the project during the closing phases.
• Incentivize documentation in some form – We have the concept of a celebration board where achievements by the team members are recorded. Whenever the board is filled up, we have a small event to celebrate that. Open-source contributions in both code and documentation form is acceptable as an achievement in this board. External requests for help and collaboration that arise from people outside our group are also recorded in this board. Often, it is the result of the well-written documentation that informs people of our work.
• Spread the word about documentation – When we do project demo presentations, we usually include the links to the documentation created during the project in the presentations wherever relevant. This has also helped get us feedback about the documentation from colleagues in other groups. Also, if someone is interested in things investigated in our past projects, we encourage them to look at the documentation to find out more. This practice speeds up the process for collaborative work.

These suggestions are based on the working style and practices followed in our group. The exact details of how to incorporate or implement them may vary from group to group based on their organizational structure and work practices. For a more generalized overview and guide about creating a culture of documentation, these external resources can be useful.

Creating a culture of documentation – Alanna Burke

How Stripe Built a Writing Culture – RC Victorino

Give your knowledge wings with documentation

Documentation is an important but often overlooked part of the software development process. However, low quality documentation leads to decreased productivity and more time spent on making sense of it. By integrating the documentation process into the development process, we can ensure that high quality documentation is generated as a byproduct of our regular work, and it is not something that needs additional time and effort. This can be done by including the documentation as deliverables in the project, budgeting for time to write documentation during the project planning phase, working on documentation in parallel with the software development process, and carrying out periodic reviews of the documentation to keep it updated. It is also important for documentation to be incentivized to encourage people to invest time in it.

Circling back to the middleware example in the beginning of this post, I made sure to create relevant documentation for the middleware as my clarity of the code increased. When this exercise was completed, there was a decent quality of documentation available for it. A year later, when a new student joined our group and was assigned to work on a different component of the middleware, I simply had to pass him the documentation and he was able to hit the ground running. He was grateful for that support, and I found an effusive mention in his thesis acknowledgments which was quite humbling to read. I wondered – I just wrote down my understanding of some code. Does it merit such high praise? That’s when I realized – knowledge is a powerful and valuable component of any organization and it is easy for knowledge to get lost if not documented properly. All of us have knowledge that is of importance to someone. Do not let that knowledge become a prisoner of your mind and set it free through the medium of documentation.