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 contract lifecycle, from origination through maintenance and renewal, in careful detail.
By her third day, she has questions. The operating model describes an automated validation step for contract amendments, run before a change is applied to a live agreement, that the system she has access to does not contain. A comment in the code, dated two years ago, reads “validation bypassed pending new pricing rules,” and those rules were never written. The validation exists in the documentation and in the quarterly metrics report, which lists amendment 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, defer hard decisions, and 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.
Structural explicitness is an act of exposure: to write a process down in sufficient detail is to declare what happens, who is responsible, and what failure looks like, and to state strategy in executable terms is to accept that it can be tested and found wanting. That is why explicitness provokes resistance, not because it is bureaucratic but because it strips away plausible deniability.
...
Continue reading in the interactive reader
Read this chapterSee also: Full contents · Preview chapters · Illusions in the Boardroom