Idée principale

Dire que le code est la source de vérité du produit s'entend spontanément comme « la documentation ne sert plus ». L'opposition est mal placée : elle n'est pas entre le code et les documents, elle est entre deux fonctions que les documents remplissent et qu'on ne distingue pas.

Un artefact qui décrit dit ce que le produit fait : une page de support sur une fonctionnalité, un changelog, une spécification fonctionnelle de l'état courant, une documentation commerciale sur ce qui est possible. Tout cela est déductible du dépôt, donc régénérable, donc sans intérêt à maintenir.

Un artefact qui explique dit pourquoi : les échanges et les raisonnements qui ont conduit à un choix, la décision produit et les alternatives écartées, la raison pour laquelle une décision en remplace une autre. Rien de cela n'est dans le code, et rien ne le retrouvera. À quoi s'ajoute ce qui ne se déduit d'aucun dépôt parce que cela vient du dehors : un engagement contractuel, une contrainte réglementaire, un document externe.

Le critère de tri n'est donc pas la forme de l'artefact ni son auteur, c'est la question à laquelle il répond. Un même document peut d'ailleurs relever des deux, et doit alors être coupé plutôt que classé.

La coupe se pratique jusqu'à l'intérieur d'une fiche. Dans une fiche d'objet produit, le corps décrit la réalité telle qu'elle est dans le code et se régénère ; le bloc des écarts porte le jugement — ce qui diverge de ce qu'on voudrait — et se maintient. La règle qui les tient séparés est absolue et se dit en une phrase : un écart ne modifie jamais le corps de la fiche. Sans cette frontière écrite, la première régénération emporte la partie qui a coûté cher à produire, puisque c'est la seule qui ne se retrouve nulle part.

Couche apportée par « J'ai écrit l'ontologie d'un produit. Trois fois, j'ai cru avoir fini. » (2026-08-11).

Pourquoi c'est important

C'est ce qui rend le déplacement vers le code opérable sans destruction. Sans cette ligne, on choisit entre tout garder — et payer la divergence — et tout jeter — et perdre le pourquoi, dont le manque ne se voit qu'au moment où quelqu'un rouvre une décision.

Cela donne aussi un test à appliquer à n'importe quel document produit avant de décider de son sort : contient-il une phrase qu'aucune lecture du dépôt ne permettrait d'écrire ?

Nuances et limites

La coupure est plus nette en théorie qu'à la lecture d'un document réel : une spécification mêle en permanence le comportement attendu et le motif qui l'a fait retenir, souvent dans la même phrase.

Et ce qui explique n'est pas exempt de péremption. Un raisonnement conservé reste attaché à un contexte d'époque ; il ne diverge pas du produit comme une description, il devient simplement moins pertinent sans que rien ne le signale.

Questions ouvertes

• Qu'est-ce qui, dans une organisation, capte les explications au moment où elles se produisent, alors qu'elles se disent en réunion et en revue de code plutôt qu'elles ne s'écrivent ?