19. La documentation vivante : préserver le raisonnement utile
Pourquoi ce chapitre existe
La documentation est souvent écrite à la fin, quand le contexte a déjà commencé à disparaître. Elle devient alors soit une paraphrase du code, soit une promesse de mise à jour que personne ne peut tenir. La réaction habituelle — « le code est la documentation » — résout le problème en supprimant précisément les connaissances que le code ne peut pas porter : pourquoi une décision a été prise, quel risque elle réduit, comment opérer le système, quelle signification a une donnée ou un contrat.
La documentation vivante n'est pas exhaustive. C'est un ensemble d'artefacts courts, proches de leur usage, qui répondent aux questions nécessaires pour changer, exploiter et apprendre.
Les idées essentielles
- Le code explique surtout le comment actuel ; la documentation conserve le pourquoi, les frontières, les contrats et les procédures de décision.
- Une page reste vivante lorsqu'elle est intégrée à un flux de travail — revue, déploiement, incident, onboarding — qui révèle rapidement son obsolescence.
- La bonne granularité dépend du lecteur et de la décision ; une documentation universelle devient rapidement illisible.
- Les tests, schémas, runbooks et ADR peuvent documenter ensemble sans se substituer les uns aux autres.
Documenter la connaissance qui coûte cher à redécouvrir
Une bonne règle consiste à écrire ce qu'une personne compétente ne pourrait pas déduire rapidement du code et des signaux disponibles. Les décisions d'architecture, les invariants métier, les sémantiques d'erreur, les responsabilités de données et les procédures d'incident répondent souvent à ce critère.
| Artefact | Question à laquelle il répond | Signal d'utilité |
|---|---|---|
| ADR court | Pourquoi cette option plutôt qu'une autre ? | Une décision est relisible six mois après |
| Contrat | Que peut attendre ou fournir un consommateur ? | Une évolution est négociée sans hypothèse cachée |
| Runbook | Comment diagnostiquer et restaurer un comportement ? | L'astreinte agit sans dépendre d'une personne précise |
| Guide de domaine | Que signifient les concepts et invariants ? | Une règle est modifiée sans réinterpréter les termes |
| Diagramme de scénario | Quels flux et dépendances importent pour ce comportement ? | Une revue identifie son rayon d'action |
Une documentation est une hypothèse soumise au réel
Un runbook non exercé, un diagramme non révisé ou un contrat non testé ne doit pas être considéré comme fiable simplement parce qu'il existe. Son usage est la meilleure validation : l'intégrer à une revue de changement, à une mise en production, à une simulation d'incident ou à l'arrivée d'une nouvelle personne révèle ce qui manque et ce qui est devenu faux.
Anti-patterns
Documenter chaque détail de l'implémentation
Une documentation qui répète les signatures, les noms de variables et la structure locale se périme à chaque refactoring et n'aide pas à comprendre l'intention. Les commentaires dans le code sont plus adaptés à une subtilité locale ; les documents doivent préserver les décisions et les relations qui traversent les fichiers.
Écrire une page centrale pour tout le système
Une encyclopédie unique devient difficile à trouver, à relire et à maintenir. Préférer des documents proches de la frontière qu'ils décrivent, liés entre eux par des entrées simples. L'utilisateur doit pouvoir commencer par une question et atteindre la connaissance pertinente sans parcourir tout le patrimoine.
Considérer la documentation comme la tâche d'une seule personne
Les personnes qui opèrent un système, prennent une décision métier ou consomment un contrat possèdent chacune une partie de la vérité. L'auteur d'un changement peut initier la mise à jour ; l'exactitude se construit avec les personnes qui utiliseront réellement l'artefact.
Bonnes pratiques
Écrire au moment de la décision
Une ADR de quelques paragraphes prise avec le changement conserve mieux les alternatives et les contraintes qu'un compte-rendu écrit après coup. Elle n'a pas besoin d'être formelle : contexte, décision, conséquences et condition de révision suffisent dans de nombreux cas.
Rattacher les documents aux preuves
Un contrat peut pointer vers ses tests ; un runbook vers les dashboards et alertes ; une page de migration vers les requêtes de validation ; un diagramme vers le code et les responsables. Ces liens n'automatisent pas la fraîcheur, mais ils rendent plus simple la confrontation entre le texte et le système réel.
Checklist — Cette documentation restera-t-elle utile ?
- Quelle question coûteuse ou risquée ce document permet-il de résoudre ?
- Quel lecteur l'utilisera, dans quel contexte de travail ?
- Contient-il une décision, un invariant ou une procédure que le code ne révèle pas seul ?
- Est-il proche du changement qui le rendra obsolète ?
- Quel test, signal ou usage régulier exposera une information devenue fausse ?
- Peut-on le rendre plus court sans perdre la raison de l'écrire ?
À retenir
La documentation vivante n'est pas celle qui change tout le temps. C'est celle qui reste reliée à une décision ou une action réelle, préserve le raisonnement difficile à reconstruire et aide le prochain changement à être plus sûr que le précédent.