Why should you write internal software documentation?

There is a certain problem with documentation. It doesn’t bring immediate value, and even when people feel that it brings benefits, it is difficult to measure that. Therefore it’s often neglected, because it’s just very easy to ignore it.

In this article I would like to highlight benefits of writing documentation.

By the way, when I say documentation I refer to the internal documentation, the company knowledge base. User documentation and manuals have slightly different characteristics.

Why should you write software documentation?

Retaining knowledge within organization.

It’s very likely that the company is going to last longer, than specific people working there. Over time, however, these people accumulate knowledge that the company execution is based on. When they leave, they take the knowledge and experience with them. So if it’s not captured ahead of time, this is a loss for the company and it makes code archeology much more difficult.

It’s easier to onboard new people.

When the employees leave, the company may look for a replacement. When new people join the team, they need to understand the domain, processes and many other things. If these things are documented, they can do it by themselves, instead of involving other people to explain the same things to them.

We’re humans. We forget things.

Even if we decide that we want existing employees to onboard new joiners, it is possible that the “teachers” forget certain aspects and every new team member goes through slightly different process, which can lead to misalignment.

But also, for current teams it can happen that engineers simply forget why things were built this and not that way, or how the specific area of the system works in general.

Accountability. If the team agrees on something, and then it’s written, it is easier to enforce the rules. Of course the written rules should be open for being challenged, but it is sometimes easy to forget certain agreements. Things like API design guide, or team role rotation.

It captures decision making process

We, as humans suffer from a hindsight bias. It’s easy to criticize certain design decisions made in the past, having the present knowledge. It helps to build empathy and understand the context, if we capture the decision making process, and trade-offs we see at a given moment.

For this I can recommend my favorite RFC template. You can find it here.

It works like a cache.

When you see the same question appearing over and over again, it may be just faster to send a link to people, instead of explaining the topic one more time. Of course capturing the knowledge takes the time initially, but if the quesiton is repeated frequently, it may bring benefits.

You can reach more people.

You can even reach people who don’t work in the company yet.
Of course you could always try to host a meeting with a bigger group. But not everyone can join at the time so it’s harder to coordinate. We can record the meeting. But then it’s harder to update it with new information. And it’s a bigger file.

It can lead to innovation and improvements.

People can stumble across documents and discover information on their own while searching for something else. That can spark ideas.

See this article to learn about how people find your documentation.

Writing the document enforces thinking.

When you want to document something, it forces you to better structure your thoughts. It may also discover areas when you, as an author, don’t understand the system yourself, and surface some design flaws.

LLMs can be trained on the documentation.

AI and LLMs are evolving quickly. We don’t know what the future will bring. Perhaps the company-specific questions could be asked to company-specific models and this could render the traditional documentation and knowledge bases obsolete. But until this happens these models need to be trained on something.

It’s easier to onboard external agencies.

When you hire an external agency, possibly you don’t put them in a regular onboarding process. But they need to understand the system nonetheless to be able to collaborate.

It makes it easier to compare the present and the past.

When you documented the system in the past, you can see screenshots from the past. This way you have a reference point to compare how the system evolved, how it looked in the past, and how it looks now (possibly better?) which could be helpful if you wanted to present something to the rest of the company.