Documentation is more important than tests

If a company would only has resources to do one, they should choose documentation

Without the intention of making a click-bait-y title, I really think docs and tests are almost equal in importance, but if a company would only have resources to do one, they should choose documentation.

Strictly looking at the code base, sure, tests are more important for the stability of the product but documentation’s impact expands beyond the code base.

It expands beyond the dev team and it shines especially when a new team member comes or goes.

Some of the main advantages of focusing on documentation that I found are:

Enriches the knowledge base of the company

At it’s basic level, the code base captures the what and how of a product but rarely it can contain the why.

Documentation can be that connection point between the business requirements and how those are implemented.

More so, documentation serves as institutional memory and knowledge preservation. When developers leave a company or move to different projects, their understanding of the codebase often leaves with them.

Onboarding new team members

Without documentation, new developers must piece together how things work through trial and error, repeatedly interrupting other devs with questions.

Good documentation can cut onboarding time from months to weeks.

Enables asynchronous collaboration

With the move to remote work also came async work. Documentation helps if a team member (be it dev, sales, etc) has a question and it wouldn’t be ideal to wait for the answer from a colleague.

We’ve seen the same wins with knowledge bases for support. It allows agents to focus a lot more

I strongly believe this does not affect cross-team communication, which is really important for not creating silos in a company. It just frees up people that are stuck by waiting for the answer from someone else.

Helps developers with “that” skill

This might be least interesting win but I think it is the biggest one at the individual level.

As developers we’re not really seen as the best communicators and I feel that writing documentation is the easiest way to develop it. You’re explaining something that you wrote and that you deeply understand. If docs also go beyond simple reference docs, that writing muscle is really put to the test.

A piece of code that we just wrote is the easiest thing to explain because we know very well what it does, we just need to connect it to the context of why.

Improves code maintainability and reduces technical debt

The act of writing documentation often reveals design issues and inconsistencies in the code itself.

If a dev uses the chain of thought think-before-you-speak trick and writes documentation before writing the code it can help a lot with having a clearer image of what he/she is about to write. Clarity in explanation leads to clarity in implementation.

There is also such a thing as Documentation driven development.

Improved dev productivity

Dev productivity is one of the hardest thing to measure but as an IC it is amazing when it happens.

The two things that are related to productivity and that documentation helps are:

We read code more than we write

The majority of the time, a dev team will update or add to an existing code base. That requires reading what’s there (in most cases, written by the same dev) and building on top of that.

The first step should always be readable code, no questions about it.

But the next big win is to add a plain english description. Even with really well written code, it is just faster to read plain english to get an idea what a method does.

Helps AI code copilots become more powerful

Another side-effect of having the code explained in plain language is that it opens up code to search by plain english. This is great for dev using using a chat based copilot but also for a multi-turn agentic system.

This is a lesson that we learned at askmanu, as we were developing the code base chat feature. We found that repos that have proper documentation perform much better during search/retrieval. This works especially well if documentation expands beyond “reference docs“.

Conclusion

Documention is an afterthought in most cases but it shouldn’t be that case.

Yes, it does take extra resources to do it, but the ROI is greater in the long term. Especially that of testing.