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.
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 Jobs To Be Done. While this won’t really help with documentation directly, it will allow you to better understand what your users need so that you can build right solutions first and then fill the gaps with the help of documentation or any other means that might work for your users.
This is thinking in users and products.
Let’s look at some examples of this:
And that’s great because as developers, we realize the value of good code quality and pay attention to it as well. So let me use this existing behavior to show that developers already think in products but only limited to their code base. If developers can write good code (the product) for other developers (their users) so that they can easily do their job of writing more code on top of our code to achieve a business objective (the value), why shouldn’t developers look at every other aspect of the job that their fellow developers are trying to do through the same lens?
Web servers, frameworks, databases, libraries, scripts, any tooling, web applications, data collection in web applications, internal applications to your company, or any piece of code which exists for other developers and internal users in your organization to use should be looked at as products. And we, as developers, don’t do that enough.
It’s true. Not thinking in products and users leads to gaps in the work we do — lack of automation, no packaging, no documentation, no guides, broken end-to-end user experience which affects productivity.
Since developers are responsible for building products for customers and building systems that affect other developers and people in an organization, they should also look at their work as product development. They should focus on value delivery to not just customers but also the organization responsible for delivering value to customers. This is why it doesn’t really matter which layer of your engineering organization are you in, as a developer you could be building features for mobile apps, building continuous delivery pipelines or writing Puppet modules for configuration management, everything that developers do creates value for someone in the organization and hence they should look at their work as product development.
A friend recently posted on Facebook:
Folks who think documentation is easy for a project, have very vague idea about project documentation.
I find a lot of truth in that statement, primarily because I find it very hard to use a lot of projects that can be potentially very useful if they had good documentation. I also believe in that statement because project maintainers who don’t work on good documentation for their project usually don’t have much empathy for their users (i.e. other developers, operations engineers, QA engineers, designers, open-source contributors, anyone who might be interested in using their project in some way), probably because that they don’t even know who all their users are. And that’s probably because they don’t think in users and products. That worries me. And because they don’t have empathy for their users, they don’t think hard enough about what they might need to be able to use their code or project easily.
Let’s explore some users who you might be working for.
Unless you are writing code for fun or for academic purposes, you are working in a team and the work you do creates value for some customers who pay you for this value. Your code could be a part of a larger code base that is exposed to your consumers as products with user interfaces.
Some of you could be working on products that are targeted to other developers which may involve using code as the interface for your users to use your product (for example, Sentry, New Relic, etc.). This is one reason why you might need documentation — for your customers (developers working in other companies) to be able to use the product you have built (your libraries) in their code or infrastructure. I think this is straight forward and does not need much explanation.
But as straight forward as it may be, there are SAAS services (that I would not name) in India that I have had to use under unfortunate circumstances that don’t care enough for a good developer experience (inconsistent or badly designed APIs with no documentation or incorrect documentation), making for a really bad developer experience (integration and future maintenance of this code), leading to more increased touch points with the support staff and account managers, leading to communication chains over email that lack full context, leading to more wasteful human involvement, leading to wasteful communication between support staff and developers because even support cannot solve all problems and have to internally trouble developers, leading to higher cost. See the point — it’s not good for any one, not even for your business. If only there was good documentation, this going round-and-round would not be necessary saving so many productive hours and mental stress.
Investment into good documentation makes business sense to deliver a good customer experience and reduce support costs.
Another reason why you might need documentation is for internal users. Seldom it happens that you work alone on any software. Almost all software is developed by a team of developers, SREs, QA engineers, product managers, analysts and designers. And depending upon how your teams are structured and work, you could have multiple internal users — a very important aspect of our work that we miss, making it really hard for internal users to work with the code we write and the software we build.
Let me bring the point of developers obsessing a lot about their code quality back. Like I said, that’s a really good thing to do. But often we limit ourselves to just the code quality and not the end-to-end experience. Some questions that as developers we should be asking are:
It is important for us to obsess over how we can give a good experience to developers who are new to our our code base (interns or new team members) or developers who get affected by our code base but don’t actively develop on it (SREs, QA engineers).
And it’s not just about developers. It’s important for us to think about other people who get affected by our code. Let’s take a look at who else can potentially get affected by our code and how:
Anybody who directly gets affected by your work is your internal user — it can be marketing, support, sales, any role really. You need to figure out what job they are trying to do and how they can do it better if you gave them documentation. It will make their and your lives easier, saving everyone’s valuable time to get more productive work done, reducing frustration, resulting into happier customers and a better business.
Either not realized or forgotten, I think we don’t get the purpose of being a developer or being in the software industry. Developers at a higher level need a bigger purpose in life than just writing code and learning more new tech — to create value for others.
As engineers, our job does not end at just writing code. Our job is to solve problems end-to-end for our users. If our software is hard for our users to use, if our code is hard for any developer to use, we haven’t really solved the problem — work done but value not created.
I think that the lack of this understanding and purpose makes it hard for developers to commit to writing documentation. Anybody who would see end-to-end value creation as their purpose would strongly believe in documentation. And a lot of developers don’t really see end-to-end value creation as their purpose, as opposed to learning and building something cool and getting away with just writing code. This is an observation from my own experiences and from my conversations with others in the industry.
I think as developers, engineering managers and leaders we need to realize this. And especially as managers and leaders, it is our job to get our teams to realize this. It is our jobs to create systems that facilitate this culture, not just because it’s a good thing to do but because there is immense value in documentation for yourself, for your team and for your business. In what amounts it is beneficial for you and your business and how far should you go with documentation so that you don’t go overboard, well that is something that you will figure out when you start believing in documentation. Just like software development, write documentation in iterations as well.
I’d like to see a deeper commitment to documentation from the industry, which is why I have written this post to explain why documentation is so important for yourself, your team and the business, and how it can create value — how we need to look at it from a different perspective. I hope it helps.
Again, this post and my opinions are based on my personal experiences in the Indian tech industry so may be this does not apply everywhere in the world. And it’s possible that I am not right about the Indian tech industry as well. But I definitely believe in my observations. If you don’t, I’d like to hear your thoughts through comments.
I started this blog post with the intent to write about guidelines for writing a good README and I realized that there is something bigger that needs to be addressed first. I will soon share the guidelines in another blog post.
If you need help with documentation culture or solving documentation related problems, reach out to me and I’ll try to help in whatever way I can.
Create your free account to unlock your custom reading experience.