Beware of Documentation Management. A Techlead's Hell Loop.

This post should be as short as “For a tech lead, time committed to working on documentation is time taken away from their immediate role”.

Let’s break down that claim.

Who is responsible for a software project’s documentation?

There are a few possible stakeholders when it comes to documentation:

1. Developers
2. Senior developers
3. Tech leads
4. Product owners
5. Project managers

Developers have self-documenting code.

Product Owners and Project Managers do not work with code on a daily basis so they often cannot create documentation.

Many times the task of writing documentation falls on :

1. Tech Lead
2. Senior Software Developer

Primarily because they know the value of having at least some documentation. Sometimes, it’s a business requirement that they are responsible for. Possibly also, because they have to answer lots of questions on a daily basis and they operate as walking knowledge bases. Instead of answering the same question multiple times, they can say Read The Fucking Manual (RTFM) but they need to have a Fucking Manual (FM) to say that.

What happens when Tech Leads write documentation?

In the case where tech leads or senior developers decide to write documentation, the issue of keeping the documentation up to date still arises.

They need to answer the question “what if the code changes?” because, without a clear answer, developers think “why should I write documentation if it could be outdated tomorrow?”.

Tech Leads cannot make demands without outlining tools and reasonable processes. Developers' time is too expensive to be spent on excessive documentation maintenance, caused by incorrect tooling.

Problem:

1. Tech Leads need to have some documentation.
2. Tech Leads cannot spend a lot of time writing documentation.
3. Developers can write documentation in a distributed way but they need to be sure that their time is not being wasted.

Current solutions for Tech Leads:

1. Don’t write documentation at all, answer questions on a daily basis. This solution will work to some extent! Especially in small companies where you do not have so many stakeholders.
2. Auto-generate documentation from code. Only good for API-like documentation but will not work for business/product documentation.

The solution: Having a system that links documentation with code

This for me seems sounds like a viable solution.

The way it works is in scenarios where you have documentation that changes once the codebase changes, you link the documentation with the code. This allows for automatic updates to the documentation that reflect changes made to the code.

For example, once a filename is changed or if a linked method/class is moved in the file, the links are updated automatically as well. You can either create software for this on your own or use existing software on the market.

Conclusion

No one will blame you for having no or limited documentation.

The same was common 20 years ago with tests. No one blamed you for having no or limited tests - because every team wrote good code which didn’t have bugs so it didn’t have to be tested :)

In the same way today, every team writes self-documenting code which everyone can read in order to understand what is inside… ;)

Let me know in the comments if I’m missing something and what you think about the idea of linking documentation with code.