Définition courte
Document court qui trace une décision d'architecture logicielle : le contexte qui l'a rendue nécessaire, les options envisagées, l'option retenue et les conséquences acceptées. Abrégé en ADR.
Définition détaillée
La pratique vient des équipes de développement et y est largement établie. Sa raison d'être est temporelle : plusieurs mois ou plusieurs années plus tard, quelqu'un qui n'était pas là doit pouvoir comprendre pourquoi un choix technique a été fait — pourquoi une file d'attente a été introduite pour traiter certains messages en asynchrone, quelles options ont été écartées, ce que le choix permet et ce qu'il contraint.
Dans les articles de ce blog, le terme est employé comme référence d'origine plutôt que pour lui-même : il sert à situer le Product Decision Record, qui reprend la structure en déplaçant l'objet du composant technique vers la règle produit. La différence de nature est celle de ce qui est tracé — un ADR fixe un choix de construction du système, un PDR une règle applicable à des situations futures.
L'ADR a une propriété que le vocabulaire produit reprend mal : il documente couramment des chantiers sans valeur métier visible. Un mois de travail sur une technologie de file d'attente ne livre rien à l'utilisateur final et peut pourtant supprimer un goulot d'étranglement, absorber dix à trente fois la charge par simple ajout de serveurs, et libérer la vente de nouveaux accès clients.
Usage dans le domaine
Le terme intervient dans les discussions sur la mémoire technique d'une équipe, sur la justification des chantiers sans livraison fonctionnelle, et comme point de comparaison dès qu'on propose un dispositif équivalent côté produit.
Synonymes et variantes
« Décision d'architecture », « ADR », « journal d'architecture ». Le pluriel « les ADR » désigne couramment le registre entier autant que ses entrées.
À ne pas confondre avec
- Product Decision Record — Product Decision Record — même forme documentaire appliquée à une règle de décision produit transverse ; il n'engage aucun choix de construction.
- Documentation d'architecture — description de l'état du système tel qu'il est ; l'ADR décrit un moment de choix et ne se met pas à jour quand le système évolue.
- Spécification technique — description de ce qu'il faut réaliser et comment ; elle découle d'une décision d'architecture, elle ne la justifie pas.
Exemples
« Une application subit une montée en charge. […] L'équipe décide alors de mettre en place une technologie de file d'attente pour traiter certains messages en asynchrone. » — la situation type que l'ADR consigne.
« Pourquoi l'a-t-on prise ? Quelles options a-t-on écartées ? Quelles conséquences accepte-t-on ? Qu'est-ce que cela permet ? Qu'est-ce que cela contraint ? » — les questions auxquelles l'entrée répond.
Ambiguïtés / débats
L'usage courant hésite sur l'immuabilité : certaines équipes tiennent leurs ADR comme des documents figés et marquent les remplacements, d'autres les mettent à jour comme une documentation vivante. Le sens retenu ici suit la première pratique, qui est aussi celle que le PDR reprend.