Main idea

Saying that the code is the product's source of truth is spontaneously heard as "documentation is no longer any use". The opposition is in the wrong place: it isn't between the code and the documents, it is between two functions documents fulfil and that nobody tells apart.

An artifact that describes says what the product does: a support page about a feature, a changelog, a functional specification of the current state, commercial documentation about what is possible. All of that can be deduced from the repository, so it can be regenerated, so there is no point maintaining it.

An artifact that explains says why: the exchanges and the reasoning that led to a choice, the product decision and the alternatives ruled out, the reason one decision replaces another. None of that is in the code, and nothing will recover it. To which you must add whatever can't be deduced from any repository because it comes from outside: a contractual commitment, a regulatory constraint, an external document.

So the sorting criterion is neither the form of the artifact nor its author, it is the question it answers. One and the same document can belong to both, in which case it should be cut rather than classified.

The cut is practised right inside a single card. On a product object card, the body describes reality as it stands in the code and gets regenerated; the block of gaps carries the judgment — what diverges from what you'd want — and gets maintained. The rule that holds them apart is absolute and fits in one sentence: a gap never modifies the body of the card. Without that border written down, the first regeneration carries off the part that was expensive to produce, since it is the only one that can't be found anywhere else.

Layer added by "I wrote a product's ontology. Three times, I thought I was done." (2026-08-11).

Why it matters

This is what makes the shift toward the code workable without destruction. Without that line, you choose between keeping everything — and paying for the divergence — and throwing everything away — and losing the why, whose absence only shows up the moment someone reopens a decision.

It also gives a test to apply to any product document before deciding its fate: does it contain a sentence that no reading of the repository would let you write?

Nuances and limits

The cut is cleaner in theory than in a real document: a specification constantly mixes the expected behavior and the reason it was chosen, often in the same sentence.

And what explains isn't immune to expiry. Preserved reasoning stays attached to the context of its time; it doesn't diverge from the product the way a description does, it simply becomes less relevant, with nothing to signal it.

Open questions

• What, in an organization, captures explanations at the moment they occur, given that they are spoken in meetings and code reviews rather than written down?