La documentation comme infrastructure

9.1 Trois niveaux d'entrée, un par lecteur

Une bonne documentation sert trois lecteurs à trois profondeurs : le nouveau venu qui a besoin de la carte, le builder qui a besoin du comment, le mainteneur qui a besoin du pourquoi. Une seule page ne peut pas bien servir les trois, alors on superpose : une vue d'ensemble au sommet, puis le guide pratique, puis la référence détaillée. Donnez à chaque lecteur la porte qui lui convient.

9.2 Une seule source de vérité par sujet

Chaque sujet a exactement une maison. Quand deux documents décrivent la même chose, ils divergent, et le lecteur ne sait plus lequel a raison. Si une information doit apparaître à deux endroits, l'un est la source et l'autre pointe dessus. Un fait avec deux propriétaires est un fait sans propriétaire.

9.3 Une décision s'écrit avec ses alternatives rejetées

La Loi 3, appliquée à la documentation. Un enregistrement de décision, ce n'est pas « on a choisi X ». C'est « on a choisi X plutôt que Y et Z, parce que, à cette date ». Les options rejetées sont la partie précieuse : elles empêchent le redébat six mois plus tard, et elles expliquent le choix à quelqu'un qui n'était pas là.

9.4 Geler, pas supprimer

Un plan ou un document obsolète ne se supprime pas. Il se marque obsolète, se date, et reste avec un renvoi vers la version vivante. La suppression perd le raisonnement, et la personne suivante redécouvre l'impasse depuis zéro. Le gel garde l'histoire à bas coût et la leçon intacte.

9.5 Le piège : le texte qui décrit du code n'est vérifié par personne

Un commentaire ou un document qui dit « cette fonction renvoie X » n'est contrôlé par personne. Le code peut changer et la phrase reste, désormais mensongère avec une totale assurance. Préférez les descriptions vérifiables (un test, un type, un exemple qui s'exécute) à la prose, et traitez tout document que vous avez écrit vous-même comme une hypothèse datée jusqu'à l'avoir reconfrontée au réel (Loi 7).

9.6 Le test d'autosuffisance : le nouveau venu à froid

Il existe un seul test pour savoir si votre documentation est une infrastructure et non une décoration : un nouveau venu à froid, un nouveau coéquipier ou un agent IA sans aucune mémoire du projet, peut-il devenir productif à partir de la seule documentation. S'il doit vous demander, la documentation a échoué, et vous êtes devenu le point de défaillance unique. Écrivez pour que la personne qui n'était pas là puisse démarrer sans vous. Une documentation autosuffisante est ce qui vous permet de passer la main, de vous absenter, ou de faire entrer quelqu'un sans réexpliquer le monde entier.