Need for better documentation

Even though we all agree about the importance of good documentation, there seems to be a widespread failure on our part to act on this belief and pay attention to how we document our software. Why does this happen?

I have often seen documentation not being the focus of teams. Somehow, teams don’t get around to realizing that documentation is as much a part of their work as producing software and hence should be a part of their definition of done.

Developers should not be the only ones who take the blame here. Their managers and leaders don’t think of documentation as a necessity, even though oftentimes they base their own decisions regarding what software to buy on the quality of the supporting documentation. The same can be said about developers when they pick open-source libraries to use at work.

So even though everybody asks for it,nobody is ready to do it when it comes to their own software. I wonder if everyone is missing something really important. It is this behavior, and our lack of commitment as an industry towards realizing that good documentation is a part of good software development that troubles me. However, I have some thoughts about how we can fix this.

We need to change how we software developers look at our work. We need to think of it as “building a product”, even when we are way back in the layer of our engineering organization as individual contributors.

We will explore this statement. Much of what I will say is based on my personal experiences in the Indian tech industry so my opinions may not be valid for everyone and I welcome your feedback.

Thinking in terms of users and products

What is a product? Mountain Goat Software defines product as:

A product is something (physical or not) created through a process that provides benefits to a market.

It’s a rather simple definition that can be applied to software development and in my opinion it is more holistic than just “writing code”.

In our case, our solution (our software) is the product, the benefit that our users get from our product is that they can do something that matters to them (a job) more efficiently, and that’s the value we deliver to our users. Every time there is a shortcoming in our product, it makes it harder for users to use it and derive that value. In the software development world, this problem is often caused by the lack of good documentation, if there’s any documentation at all.

All software should be built keeping in mind who is it for and how are they going to use it — something we often miss while writing code when “building that feature” becomes our only goal instead of trying to solve the problem that led us to building that feature in the first place.

What are these users trying to do? In order to figure out what our users are really trying to do, I like to follow this framework called


Need for better documentation was originally published in Hacker Noon on Medium, where people are continuing the conversation by highlighting and responding to this story.