Idea

The divergence between documentation and code is a cost trade-off, not negligence

Info

Originally written in French. Translated by AI — the meaning has been preserved, not the prose.

Main idea

When a team notices that a specification is out of date, the reflex is to see a lack of rigour in it. The mechanism lies elsewhere. With every change, however minor, you would have to find the right specification, the right mockup, the right support document and the right changelog entry, then correct them all. That work is proportional to the number of artifacts, not to the size of the change: fixing one label can mean touching five documents.

On a living product, adjusted and enriched over months or years, the sum of these resynchronizations exceeds the time available. Nobody decides to let things diverge; each person decides, once more, that this is not what they will do with the next hour. The divergence is the cumulative result of those trade-offs, all of them reasonable taken one by one.

That is why remediation by discipline does not work: it asks you to win a cost trade-off by willpower.

Why it matters

It moves where the solution lies. As long as the divergence is read as negligence, the answer comes in rules, reviews and reminders — which add cost to a gesture that is already too expensive. Read as a cost trade-off, it calls for an answer on the cost: reduce the number of artifacts to maintain, or reduce the price of updating them.

It also avoids attributing to a team a flaw that belongs to the structure of its work.

Nuances and limits

The trade-off is not equally defensible everywhere: a changelog delivered to the customer and an internal working mockup do not have the same consequence when they drift. The cost saved is not paid in the same place.

And the demonstration holds for a product that evolves continuously. On a frozen scope, resynchronization is a one-off cost, and the argument collapses.

Open questions

  • How do you measure the cost actually paid for a divergence, so as to compare it with the cost of upkeep?