Documentation has a reputation problem. Ask software engineers how they feel about documentation and many will describe it as something they have to do rather than something they want to do. Documentation is often incomplete, outdated or ignored. It is frequently treated as a deliverable rather than an asset. Perhaps that is because we have forgotten why documentation exists.
A while ago, I worked with a CTO who openly disliked system documentation. His preferred solution was different: everyone should work on everything. If every developer understood every part of the system, knowledge could not become concentrated in a few individuals.
I understood the concern. When critical knowledge exists only inside a handful of people’s heads, every resignation, holiday or illness becomes a business risk. But the proposed solution never convinced me. t always felt like the wrong solution to the right problem.
Making everybody know everything may work for a small team and a small product. As organizations and systems grow, however, it becomes increasingly unrealistic. Complexity grows faster than any individual’s ability to understand it all. Perhaps the answer is not to make every person know every system. Perhaps the answer is to make every system preserve enough of its own meaning that future people can reconstruct why it is the way it is.
That leads to a different question:
What is documentation actually for?
We often think documentation describes a system. It doesn’t.
The source code already describes the implementation. Configuration files describe the environment. Databases describe the data. APIs describe the interfaces. If documentation merely repeats information that already exists elsewhere, it quickly becomes redundant—and eventually outdated.
The real purpose of documentation is different. Documentation exists to preserve meaning. Future developers can usually discover what a system does. What they cannot easily reconstruct is why. Why does this system exist? Why was this architecture chosen? Why was this dependency accepted? Why is this apparently strange business rule still enforced? Why was this workaround considered preferable to fixing the underlying problem? Those answers rarely exist in the code itself.
When the people who understood those decisions leave, the implementation remains. The system continues to run. But the understanding slowly disappears. Maintenance then becomes archaeology. Every unusual piece of code raises the same question: Was this deliberate, or simply forgotten?
This is where documentation earns its place. Not by attempting to explain everything. Not by describing every class or every method. But by preserving the things that future people cannot easily rediscover for themselves. The assumptions. The trade-offs. The decisions. The stories. The reasons.
Documentation should preserve enough context that future people can reconstruct the original meaning. Perhaps that is the real why of system documentation. Not to describe the system. But to ensure that understanding survives the people who created it.
Because continuity is not achieved when everybody knows everything. Continuity is achieved when the next person does not have to start from zero.
Leave a Reply