Rédiger un ADR à partir d’une discussion d’architecture enregistrée
Un ADR documente une décision d’architecture importante : contexte, options, choix, conséquences et statut. La transcription aide à retrouver les arguments. Les participants confirment l’exactitude technique.
Comment rédiger un Architecture Decision Record à partir d’une discussion enregistrée
Un ADR documente une décision d’architecture importante : contexte, options, choix, conséquences et statut. La transcription aide à retrouver les arguments. Les participants confirment l’exactitude technique.
La transcription permet de vérifier les formulations. Elle conserve le contexte, les nuances et l’ordre des arguments. La personne qui rédige arrête le texte final et le fait relire aux participants.
Rédigez l’ADR par étapes
Choisissez une décision
Consignez chaque décision d’architecture indépendante dans sa propre fiche.
Décrivez le contexte
Notez les facteurs et les contraintes qui ont rendu la décision nécessaire.
Comparez les options
Gardez pour chaque option les principaux avantages, inconvénients et raisons de l’écarter.
Précisez les conséquences
Listez les bénéfices, les coûts, les nouvelles contraintes, les risques et la condition de réexamen.
Exemple pédagogique : choisir le stockage des fichiers audio
L’exemple pédagogique ci-dessous est fictif. Les noms, les conditions et les résultats servent uniquement à expliquer la méthode.
« Le stockage objet coûte moins cher pour l’archivage, mais il nous faudra un mécanisme distinct pour les liens temporaires. »
Contexte : les enregistrements sont volumineux, la durée d’accès doit être limitée et la création des liens contrôlée. Le choix se porte sur le stockage objet. Le coût compte avec la capacité de montée en charge et le modèle d’accès.
Précisez le travail et les risques : liens temporaires, contrôle de leur validité, journalisation et essais en cas d’échec. Si l’hypothèse de coût change, un nouvel ADR peut remplacer celui-ci tout en conservant l’historique.
| Section | Formulation utile | Exemple à éviter |
|---|---|---|
| Contexte | Fichiers volumineux et accès limité | Il nous faut un nouveau stockage |
| Options | Stockage objet / stockage de fichiers | Nous avons retenu le meilleur |
| Décision | Stockage objet pour les raisons A et B | L’architecte l’a décidé |
| Conséquences | Liens temporaires et suivi | Aucun inconvénient |
Modèle d’ADR
Copiez le modèle et remplissez-le à partir d’un enregistrement précis. Présentez les suppositions comme des hypothèses.
Titre et statut : Date et participants : Contexte et contraintes : Options examinées : Décision et raisons : Conséquences, risques et condition de réexamen :
Quatre vérifications avant envoi
- La fiche documente une décision.
- Le contexte décrit les contraintes réelles.
- Les options et les raisons de les écarter sont consignées.
- Les inconvénients et une condition de réexamen sont indiqués.
Dans le détail
Peut-on modifier un ADR accepté ?
Les coquilles peuvent être corrigées. Un changement de décision mérite un nouvel ADR lié au précédent.
Faut-il conserver la transcription à côté de l’ADR ?
Un lien vers la source interne et un repère temporel suffisent généralement pour vérifier une formulation discutée.