Somewhere in a German company there is a Confluence space with 847 pages. Twelve of them are current. The other 835 describe systems that no longer exist, processes nobody follows anymore, and decisions made before three reorganisations ago.
That is not IT documentation. That is a digital archive for bad conscience.
Why do we document in the first place?
The honest answer: because we are afraid. Afraid that someone leaves and takes the knowledge with them. Afraid that in six months we will not remember why we built it that way. Afraid of the audit. Afraid of the handover.
These are valid reasons. But they lead to the wrong answer: document everything. Always. Completely. With a template. The result is familiar: documentation that is outdated before the ink is dry, because changes never find their way there.
What documentation can really cost
Documentation is not free. Every hour a developer spends writing down things that are already in the code is an hour they are not building.
And then the real problem arrives: documentation needs to be maintained. A system changes. The hosting moves. A dependency disappears. Who updates the docs? Nobody. Because there is no capacity, no process, no ownership. So it stays, gets older, and becomes reliably wrong.
Wrong documentation is worse than no documentation. It creates confidence that does not exist.
When you do not need docs
Anyone who can read code often does not need separate documentation. Good code is self-documenting. Clear variable names, small functions, understandable structure, that is the documentation.
That does not apply to everyone. But it applies to more situations than most teams admit.
README.md: the standard that stuck
Fortunately a pragmatic solution has established itself for code: the README.md. Right in the repository, exactly where the code lives. Anyone who opens the project sees it immediately.
No separate wiki. No Confluence space three clicks away. No tool that requires a separate login. The documentation lives where the code lives, and is therefore automatically kept visible with every commit.
And one step further: connecting README.md files and code repositories directly into a company's LLM knowledge base enables something useful. The LLM can then explain what the code does not just for developers, but also make the logic understandable for non-technical people. Product management asks what a certain process does and gets an answer in plain language, not stack traces.
What actually needs to be documented
Not everything needs docs. But some things absolutely do. The difference is not in the code, it is in the context.
What stays: where is the hosting? Who has access to what? Which external services are connected and who pays for them? What happens if system X goes down? Who gets called?
These are not technical questions. They are operational questions every company needs to be able to answer, regardless of whether someone is sick, on holiday or has handed in their notice.
In short: do not document the code. Document the context. Where things live. Who owns what. What happens when something goes wrong.
The LLM trick almost nobody uses
A developer who feeds their code into an LLM and asks “tell me what this code does and write a readme” gets something in three minutes that used to take an hour.
That changes the calculation completely. The effort required for technical documentation has dropped by a factor of ten. Those who ignore this are still paying the old price for something that has become far cheaper.
What remains
IT documentation is not an end in itself. It is a tool. And like every tool it is useful when applied correctly, and dead weight when applied to everything.
Three questions every team should be able to answer: where is the hosting and who has access? What are the critical external dependencies? Who do you call when something is on fire?
Everything else follows, from the code, from the context, or from an LLM that summarises both.
— Robert
