Documentation That Lies

The Diagram on the Wall

Most engineering teams have one. A large architecture diagram, printed or pinned to a Confluence page, produced by someone thorough at some point in the past. It shows the services, the connections, the data flows. It was accurate on the day it was made.

That was eighteen months ago.

Since then, two services were split. One was retired but the traffic still flows through a legacy route nobody updated. A third-party integration was added during a sprint that moved fast. The database that was supposed to be read-only has two write paths now, one of which the security team does not know about.

The diagram says none of this. But it looks authoritative. It gets shared in onboarding. It gets attached to audit responses. It gets used to make architectural decisions. And every time it does, the gap between what people believe and what is actually true widens a little further.

Why Documentation Goes Stale

The usual explanation is discipline — teams just need to be better at updating the docs. This is not wrong, but it misses the structural reason documentation goes stale in the first place.

Software changes constantly. Documentation changes manually. These two things cannot stay in sync at scale — not because engineers are careless, but because maintaining documentation is a separate job from writing software, and it competes with that job for the same time and attention.

The person who built the new integration is not thinking about the architecture diagram when they merge their pull request. The person who updated the deployment config is not updating the data flow doc. Nobody is. The docs exist in a separate system, edited by hand, with no connection to the thing they describe.

When the cost of updating documentation is greater than the cost of leaving it stale, it will be left stale. That is not a people problem. That is a systems design problem.

The Consequences Are Not Theoretical

Stale documentation has real costs — some operational, some regulatory, some security-critical.

Incident response slows down. When something breaks at 2am, the team is working from a mental model of how the system behaves. If that model is wrong, the investigation takes longer. False assumptions get followed. The wrong services get restarted. The actual cause stays hidden.

Security reviews miss the real surface area. A penetration test or threat model based on an outdated architecture is not a security review — it is a review of something that no longer exists. Real vulnerabilities in the actual system may never be found.

Compliance audits become creative writing. Data protection impact assessments, GDPR compliance, SOC 2 evidence — all of these require accurate knowledge of how data flows, what systems process it, and who has access. If the docs are wrong, the compliance case is built on fiction. That is not a problem until it is a very serious problem.

New engineers inherit wrong mental models. The onboarding engineer reads the architecture doc and learns a system that does not exist. Every decision they make is subtly miscalibrated. Over time, this compounds.

The Fix Is Not More Discipline

Asking people to keep documentation updated is asking them to do two jobs simultaneously: build software and maintain a parallel record of what the software does. This works for a while, in small teams, on focused systems. It does not scale.

The only documentation that stays accurate is documentation that cannot get out of date — because it is derived directly from the system itself.

This is not a new idea. It is why we generate API documentation from code annotations rather than writing it by hand. It is why we prefer infrastructure-as-code over wikis full of provisioning steps. It is why runbooks that execute commands are more reliable than runbooks that describe commands.

The principle is the same in every case: tie the documentation to the source of truth, not to a human remembering to update a document.

What That Looks Like for Architecture and Data Flow

For architecture to stay accurate, the architecture needs to be derived from what is actually deployed — the services, their connections, their interfaces, their data flows — not from what someone believed was deployed when they last opened the diagramming tool.

This requires the platform to have a structural understanding of the application estate. Not monitoring data. Not logs. The actual definition of what applications exist, how they communicate, what data they handle, and where they run.

When that exists, architecture diagrams stop being documents and become views. Data flow diagrams stop being audit artefacts and become live reports. The compliance case stops being an approximation and becomes a derivation from the actual system state.

The question shifts from “is this documentation accurate?” — which requires human verification — to “is the system state accurate?” — which is a much more tractable and answerable question.

That is the difference between documentation that lies and documentation that cannot.