Je voulais vous (re)présenter les ADR dans cet article.

C'est une tendance qui monte depuis quelques années (même s'ils ont été créés en 2011, paternité de Michael Nygard).
En 2024, ça devrait être un passage obligé, mais c'est encore loin d'être le cas.

Sommaire :

• Qu'est-ce qu'une Architecture Decision Record (ADR) ?
• Pourquoi les ADR sont-ils à la mode ?
• ADR: le chainon manquant ? (en 15')
• Conclusion

Qu'est-ce qu'une Architecture Decision Record (ADR) ?

1 ADR = 1 réunion + 1 CR sur une décision d'architecture

Une ADR se fait en collaboratif, avec toutes les personnes sachant nécessaires pour couvrir le périmètre.

La décision finale se fait de manière collégiale et doit être unanime.

On va y préciser :

• les personnes ayant participé à cette décision,
• le contexte le plus clair et précis
• les problématiques et contraintes
• les différents scénarios/décisions possibles
• le choix final
• les raisons de ce choix
• les conséquences et impacts

Le CR va servir de livrable traçant la décision.
Son remplissage va aussi servir de guide pendant les échanges permettant la décision.

Une ADR va porter un cycle de vie associé.
Elle sera valable tant qu'une nouvelle ADR ne la remplace pas et que la solution associée existe.

Pourquoi les ADR sont-ils à la mode ?

• Transparence et traçabilité : Comme ce sont des comptes-rendus, leur diffusion permet une transparence et une traçabilité sur les décisions prises. Elles améliorent aussi le suivi de la dette associée.

On évite le "c'est historique / les gens sont partis"

• Facilitation de la prise de décision : En formalisant la structure des décisions, les ADR facilitent les discussions et permettent de prendre des décisions plus éclairées. Ils permettent également de documenter les conséquences du choix.

On peut/doit évoquer les alternatives et détailler pourquoi elles ne sont pas retenues

• Amélioration de la maintenabilité : En conservant un historique des décisions, les ADR facilitent la compréhension du système et de ses évolutions. En traçant les conséquences des choix, ils facilitent la gestion de la dette.

Cela implique une gestion documentaire qui permet de retrouver toutes les ADR

• Onboarding facilité : Les nouveaux arrivants peuvent trouver facilement les décisions ayant amené à l'architecture du système actuel en consultant les ADR.

ADR: le chainon manquant ?

En commencant à utiliser les ADR, alors que je devais rédiger des DAT,
je me suis rendu compte que c'était un type de documentation qui manquait dans la documentation.

J'ai pu assister à un talk du Devoxx 2023 qui parlait de ça et qui m'a complètement convaincu.
Du coup, plutôt que de le paraphraser, autant que vous visionniez le Talk :

(youtube) Talk ADR: Le Chainon manquant (Sylvain Aurat) 15'

Conclusion

les ADR sont une solution simple pour documenter les concepts de la solution

Si on se réfère à Diataxis, dans les 4 formes existantes, une forme doit répondre au "Pourquoi ...?" => les Concepts.

Dans la méthode Diataxis, *les ADR sont une forme de Concept *