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 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:

1. Web servers, databases, firewalls, etc. are all products. Their users are developers or sysadmins who are trying to the job of setting up an IT infrastructure to achieve a business objective. Often open-source projects with bad documentation receive a lot of criticism because somebody had a hard time trying use some obscure functionality which they needed but had a hard time finding about it. They had a hard time trying to do their job and your product (the open-source product) failed to deliver a good user experience. Example: postgres, AWS Security Groups, nginx.
2. Libraries, scripts, developer tools are also products that other developers are trying to use. They can’t do their job well if there is not enough documentation on how to use these products. As a maintainer of these products, it’s your job to step into other developers’ shoes and provide them with the necessary documentation, training, demos, etc. Some great examples of this: python-requests, Chrome DevTools, Sublime.
3. If your micro-service is going to be integrated by another team in their micro-service, they are going to need your micro-service’s documentation to do that integration. In absence of this, there will be a lot of to and fro between your team and the team trying to use your APIs, wasting their time and your time. And it would require future maintenance so expect more time wastage. The team (your users) trying to integrate your service with theirs are trying to do the job of building a micro-service using your micro-service to achieve certain business goal. Lack of documentation is slowing them down, degrading their experience.
4. If you do not document common issues and troubleshooting guides for fixing production issues, how would your ops teams (or SRE, DevOps, or whatever you call them) will help you maintain that software in production. In absence of this, it will take your SREs and you a lot more time to fix production issues. Your SREs are trying to do the job of making sure that production is stable, and your code is working as expected. They are your users as well.
5. This can feel like a stretch to some people but I think it’s true — even the functions you write and the classes you build are products for other developers in your team. That’s why you pay so much attention to the design of your code so that it makes sense to others in your team and they can do their work alongside your work.

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.

We should think in terms of users and products. And the documentation we write is a part of our product that creates value for our users who are trying to do their job.

Who are we working for?

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.

Customers (who pay for your code)

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.

Internal Users

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:

• How can my QA engineer set up that service locally for testing?
• What metrics in production should our SREs watch out?
• How can the new intern or team member set this project up for development quickly?

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:

1. The most important — your work matters the most to your customer. Most developers never work directly for their customers and have a layer of business people or product managers in between who will take care of relevant documentation for customers. But if you are building a product that is used by other developers (for example, Loggly, Sentry, New Relic, etc.), it’s easy for you to be able to step into their shoes and try to figure out what they might need to use your product or your code easily. Most of us would not be working for companies building such developer tools but a lot of us probably have open-sourced our work, which we should look at from the same perspective. Mostly documentation as web pages of text explaining how to use APIs or the interfaces that you expose but can also include working demos, presentations, videos, try it yourself demos, etc. Yes, videos can be treated as documentation as well. It really depends on what works for your users.
2. Other developers in your team (even yourself) — are also your users. If you are working on a team trying to solve a problem and as a part of that you write a library that someone else on the team has to use, how are they going to use it without any documentation and get their job done. In absence of documentation, they will ask you or try to read your code. Both wastes your team’s valuable time and adds context switching. And what do you do when you don’t work on that library for a few months and now have to fix that nasty bug. I bet you will forget it yourself what the library does, how to set up it’s dev environment, how to run tests, etc. if you don’t have documentation for each of those things.
3. New developers joining your team — lack of documentation often leads to a very bad on-boarding experience for engineers. The only way a new engineer can get up and running is by a lot of hand-holding from exisitng members and hit-and-trial — which again wastes the team’s time and the time it takes for the new member to be productive. Not to forget that your new member is going to be frustrated. I’m not saying that documentation would remove the need for hand-holding but it can definitely reduce it to a great extent. Ask yourself — is your project documented enough that a new team member can commit and deploy a minor fix to production on the same day?
4. Other developers in your company but not in your team — big companies with good engineering culture save time and money by reusing their existing solutions. Why build something that has been built before? Why solve a solved problem? Why reinvent the wheel? It makes sense, right. But are you doing enough to make that not happen? Do your projects have enough documentation that anyone else in your company can discover them, know what they do, can easily set them up and start using them? If they are having a hard time using these projects, can they reach out to you for help instead of building it all over again? And if they find your work super useful, can they submit a patch to add a new feature or fix a bug that can help everyone in the company? Good engineering teams make the most of the economies of scale by increasing collaboration. Collaboration has to be assisted by good documentation because face-to-face interaction might not be possible or too difficult. It’s important that you document not just for yourselves and the team that you work with but also others who can potentially benefit from your work to avoid waste, save yourselves from rebuilding something that already exists and use that time and money for creating something new and more impactful. It makes sense business wise and is a better use of your time at a personal level as well.
5. Developers outside your company (open-source) — point 2, 3 and 4 also hold true if you are working on open-source projects or if your company decides to open-source something. If you follow point 2, 3 and 4 properly, this might be easy to achieve since you already have most of the work done. Open-sourcing or not is also your company’s decision, but great companies benefit a lot from open-sourcing. So it actually might make sense to develop your software which is ready to be open-sourced with minimal effort, which means that there should be focus on documentation from the beginning.
6. UX Designers? — this is subjective but I think it makes sense from my recent experiences and can vary from team to team. Your front-end team could be building a UI toolkit in collaboration with your UI designers so that your UX designers can use that toolkit to quickly develop new features and solutions. Without a good documentation of the capabilities of your UI toolkit, it will be hard for your UX designers to work on new solutions because they don’t really know the strengths or the weaknesses of your frontend platform. Documentation of a UI toolkit doesn’t have to be how we conventionally think of documentation. It can very well be a demo interactive website that just shows all the capabilities, like Bootstrap.
7. Product Managers and Analysts — are also users. They make product and business decisions on the basis of the data that your product collects. Without enough documentation of what data is getting collected, it will be hard for them to make sense of the data that your code base collects, making it harder to analyze product performance, troubling you from time to time to ask the meaning of every event data, and again wasting their and your time.

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.

Developers need a bigger purpose

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.

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.