Originally written in French. Translated by AI — the meaning has been preserved, not the prose.
Angle
A product's code establishes how it works and does not carry its meaning: the rule you can only state after reading five files, an object's special cases, the words customers use, the scope of a notion that changes from one application to another cannot be read there, and are spread across the core of the code, the database, the screens and the translations. That meaning does exist, though, in the heads of a few people, and it was passed on perfectly well as long as you could knock on the right colleague's door. Two things make it untenable today: every department reconstitutes that model for itself — documentation, tender responses, training, support — at an expense that appears in no budget; and an agent knocks on no door: what has not been written, it fills in plausibly, coherently and sometimes wrongly. Writing down the product's model — its objects, their links named by verbs, their rules, their words — therefore does not replace the code: it is the only way to make usable what the code is authoritative on.
Synthesis
The shift that made the code the reference was right: it did away with the work of keeping up to date documents that described something other than reality. These notes say what it left aside, and why the bill is arriving now.
They answer one another on three planes. On the nature of what is missing, first: neither a narrative nor an isolated definition, but a structure — objects linked by precise verbs, rules stated in one sentence, a lexicon on several levels. On dispersion, next: this meaning is not absent, it is scattered, and each of the four places where it settles says what the others leave unsaid — with, as a result, the internal contradictions you only see by bringing them face to face. On the economics, last: permanent reconstitution cost nothing visible as long as it was human, and the move to addressees who cannot ask brings the price into view.
The benefit is not limited to documentation. A rule written in business language is a test as it stands; a customer report is qualified mechanically according to whether it contradicts a written rule or reveals a rule never laid down; a notion with no place of definition stops producing three different balances on three screens. These are distinct uses of one and the same artifact, and that is what separates this work from one more piece of documentation.
Tensions / contradictions
None of this is measured. The mechanism is clear — you remove the guessed-at share — but the operating phase has not begun, and no comparison has been made between requests handled with and without the reference model. The notes carrying the uses therefore describe an expectation, where those carrying the cost describe an observation.
Second tension, with the code-as-source-of-truth doctrine: the reference model reintroduces a hand-written artifact, therefore one liable to diverge from the product — exactly what the move towards the code had eliminated. The answer held here is an internal boundary, a regenerable body and maintained gaps; it remains to be tested over time.
Questions
- What share of a product's mental model has no chance of being written down, because it is only formulated at the moment a precise question calls for it?
- What becomes of the artifact when two applications in the same suite give a different meaning to the same word: one record per scope, or one record carrying both?
- On what conditions do the functions that do not read code — support, pre-sales, training — contribute to this reference model instead of merely consuming it?