Documentation is part of engineering

Documentation is conventionally understood as a description of a system, produced after the system exists, for the benefit of people who did not build it. Under that definition it is hygiene — worthwhile, secondary, and the first thing dropped under schedule pressure.

The principle: a component requires a written argument for its existence before it is built, and the argument is engineering work rather than a description of it.

What the argument has to contain

Not a description of what the component will do. An argument for why it should exist: what it is responsible for, why that responsibility cannot live in something that already exists, what alternatives were considered and why they lost, and what would have to be true for this to be the wrong idea.

The last item is the one that does the work. A justification that cannot state its own falsification condition is usually a preference that has been written in the register of a reason.

Why it belongs before the code

Because a meaningful fraction of the time, writing it is how you discover the component should not exist. The responsibility turns out to belong to something already present, or the problem it addresses turns out to be a symptom of a problem one layer down.

The economics are lopsided enough that the practice pays for itself even at a low hit rate: an hour of writing against a week of building, the ongoing maintenance of something that should never have existed, and the considerably larger cost of only discovering the mistake once the architecture has grown around it.

Documentation written afterwards cannot do this. By then the decisions are made and the honest options are to describe what exists or to misrepresent it. So it describes, and the description is accurate and nearly worthless, because the part a future reader needs is the part that is gone — the alternatives, and why they lost.

The symmetry worth noticing

This is the same argument as explainability before automation, applied to people instead of components. An explanation generated after the fact by a separate process is a reconstruction, whether the process is a neural network or an engineer writing a design document from memory. In both cases the account must be produced by the same activity that produced the decision, or it is a story about the decision.

The failure mode

Documents are pleasant to write. They feel like progress and cost nothing to be wrong about, and it is entirely possible to spend a week architecting something that two days of building would have settled empirically.

The boundary in use: write the document when the cost of being wrong is structural. Anything other components will depend on, anything expensive to reverse, anything touching the authority boundary — document first. Anything that can be deleted in an afternoon — build it and find out.

Erring toward writing is slow. Erring the other way produces a system nobody decided on, which is not recoverable by working harder.