Adr

Situation réelle Pourquoi cette décision a été prise ? Qui l’a validée ? La documentation ne le dit pas… ou elle est obsolète. Cette situation n’est pas une fatalité. Les ADR et RFC résolvent ce problème de façon élégante. Ce que j’ai observé : beaucoup d’équipes ont une documentation morte. Symptômes classiques (README.md last updated 2 years ago “We use microservices…” mais personne ne sait pourquoi microservices quelles alternatives considérées qui a décidé). Résultat: décisions refaites plusieurs fois, contexte perdu, nouveaux arrivants perdus. Avec ADR/RFC, documentation vivante : toujours à jour archives immutables, contexte préservé, décisions traçables. Métriques adoption mesurée (Avant ADR/RFC décisions documentées 10% “Pourquoi ?” répondu rarement onboarding nouveau 2 semaines, Après ADR/RFC décisions documentées 95% “Pourquoi ?” dans ADR toujours onboarding nouveau 3 jours). ...

Situation réelle “Pourquoi on a choisi cette architecture ?” Cette question revient 6 mois après chaque décision importante. Sans documentation, le contexte est perdu, et on refait les mêmes débats. Ce que j’ai observé : les ADR (Architecture Decision Records) sont l’outil le plus sous-utilisé et le plus utile pour la gouvernance technique. Ils coûtent 30 minutes à écrire et économisent des heures de débats futurs. Le faux problème Le faux problème serait de croire que “le code se documente lui-même”. En réalité, le code explique le “comment”, pas le “pourquoi” ni les alternatives considérées. ...