What Was Never Written Down
Most organisations suffer not from a lack of documentation but from a lack of documents that are structurally permitted to be true. An artefact only matters if it removes options, collapses ambiguity, and forces consequences.
The new senior engineer spends her first week reading. The team lead has been thorough: a shared drive with architecture diagrams, a Confluence space with process descriptions, a wiki with onboarding guides. There is an operating model document, updated seven months ago, that describes the end-to-end vehicle configuration-to-delivery pipeline in careful detail.
By her third day, she has questions. The operating model describes an automated validation step for customer configurations, run before an order enters the manufacturing queue, that the system she has access to does not contain. A comment in the code, dated two years ago, reads “validation bypassed pending new battery config rules,” and those rules were never written. The validation exists in the documentation and in the quarterly metrics report, which lists configuration validation rates as a KPI; it does not exist in production.
The new senior engineer asks the team lead, who is not surprised. “That document describes what we were building towards,” he says. “The system describes what we actually did.” He opens a Slack channel and scrolls to a thread from eighteen months ago. “This is where the real decisions are. Most of them, anyway.”
Over the next two months, she will learn what the system does, one incident at a time, and will understand why nobody updated the documentation: doing so would mean admitting how far the system has drifted from what was approved, an admission that carries a cost nobody has been willing to pay. Most software-dependent corporates suffer not from a lack of documentation, but from a lack of documents that are structurally permitted to be true. The artefacts exist in abundance, creating the appearance of clarity without constraining behaviour.
The crucial distinction is between writing something down and committing to it. An artefact only matters if it removes options, collapses ambiguity, and forces consequences.
In organisations where reality is optional, documents are designed to do the opposite. They preserve flexibility. They defer hard decisions. They can be agreed without changing how anything works.
Every reader has met the document that is sixty pages long, was reviewed by eleven people, took three months to produce, and constrains nothing. Its purpose is to be referenceable, not to be true, like a safety certificate hanging in a building that has never been inspected.
Recording states without committing to them is why so many artefacts feel empty: states without transitions, goals without mechanisms, outcomes without ownership.
...
Continue reading in the interactive reader
Read this chapterSee also: Full contents · Preview chapters · Illusions in the Boardroom