The Unseen Anchor: On the Peril of Over-Documenting
We are told, from our first days tinkering with a server, that documentation is sacred. The mantra is repeated in every ops room, every forum, every post-mortem: ‘If it isn’t documented, it doesn’t exist.’ We fill wikis with elaborate runbooks, comment our configuration files like sacred texts, and diagram our networks until they resemble subway maps of a metropolis we’ve never visited. This is presented as an unalloyed good, the mark of a professional. But I want to propose a heretical thought: excessive documentation can become a silent, dragging anchor, holding your systems—and your team—fast to a past that no longer exists.
The danger lies not in the act of recording, but in the illusion of completeness it creates. A perfectly documented system suggests a finished thing, a solved equation. It implies that all the mysteries have been tamed and neatly categorized. This is a fiction. Our systems are not static exhibits in a museum; they are living, breathing entities that evolve through patches, workarounds, and the gradual accretion of technical debt. The most crucial knowledge—the ‘why’ behind a seemingly irrational configuration, the memory of that one-off fix applied during a holiday outage—often exists only in the minds of those who did the work. No document can truly capture it.
The Weight of the Past
Worse, outdated documentation is actively malicious. It is a siren song leading future maintainers onto the rocks. We’ve all been there: spending an hour tracing a configuration line-by-line against a wiki page, only to discover the page describes a service decommissioned two years prior. The time wasted is bad enough, but the erosion of trust is far more costly. When a team learns that the documented ‘source of truth’ is often a lie, they stop consulting it altogether. The elaborate wiki becomes a digital ghost town, a monument to a project that was once important. The act of documentation, intended to save future time, instead burns it in a futile ritual of verification.
This is not a call for anarchic silence. It is a plea for intentional, living communication. Instead of striving for exhaustive, encyclopedic records that will inevitably decay, we should focus on lean, high-signal documentation. Document the intent, not just the implementation. A single line explaining *why* a specific timeout value is set to 300 seconds is infinitely more valuable than a thousand lines auto-generated by a tool describing every parameter. Foster a culture where a quick, verbal ‘hey, why is this like this?’ is not seen as a failure to read the docs, but as the most efficient way to transfer the living, breathing context that no document can hold.
Our duty is not to create a perfect archive of a system’s current state, but to build a team that can navigate its constant flow. Sometimes, the most reliable knowledge is not what is written down, but what is shared in the moment, between people who are deeply engaged with the machine as it is, right now, and not as it was documented to be six months ago. The true pulse of a system is felt, not read.
Notes & further reading
A few pages I came back to while writing this: