Suivre les décisions d’architecture avec les ADR

The Big Picture

Les ADR ( Architectural Decision Record) sont une documentation des décisions d’architecture que Michael Nygard a formalisée en 2011 dans un billet sur le blog de Relevance (devenu Cognitech depuis). Pour les lecteurs moins à l’aise avec la langue anglaise, je propose une traduction du billet en français sur un petit dépôt sur GitHub avec d’autres ressources sur les ADR en complément de cet article.

Cette documentation légère est adaptée à des projets agiles (mais peut bien sûr être utilisée avec profit dans un contexte non-agile). Souvent écrite en Markdown ou AsciiDoc ou un format de ce type, elle est alors suivie en gestion de configuration avec le code source (principe de la documentation-as-code). Cependant, elle peut également être gérée via le wiki du projet ou exister à travers des documents textes classiques voire des slides.

L’objet d’un ADR est de garder un historique des décisions concernant des exigences d’architecture significatives afin que ces choix restent compréhensibles même pour de nouveaux arrivants. Un ADR capture le contexte et les conséquences de la décision au moment où cette dernière est prise. Cela permet ainsi d’avoir de la perspective sur les décisions passées et d’avoir des éléments pour prendre des décisions éclairées pour les besoins présents du projet en tenant compte de ces choix passés.

Les ADR en questions

Est-ce que les ADR documentent une solution ?

Un ADR décrit une décision sur une exigence fonctionnelle ou non-fonctionnelle structurante : cette décision relève de l’architecture car elle a un effet significatif sur le projet ou le produit concernée par elle. Par contre un ADR ne décrit pas une solution ou n’expose pas une conception : c’est un enregistrement d’une décision et rien de plus.

Les ADR sont une forme de documentation légère et efficace particulièrement adaptée aux projets Agile. Les ADR s’ils sont correctement mis en place, sont une forme de documentation utile qui a sa place dans tout type de projets dans lesquels la traçabilité des décisions d’architecture est importante.

Pourquoi utilise-t-on des ADR ?

On utilise les ADR pour garder un historique des décisions d’architectures significatives, c’est-à-dire des décisions qui affectent par exemple la structure, les caractéristiques “fonctionnelles” ou “non-fonctionnelles” (performance, scalabilité, élasticité, sécurité, etc.), les dépendances, les interfaces ou la mise en place de composants techniques (bases de données, middlewares, etc.) au niveau de l’architecture du produit, du projet ou de la solution concernée.

Mais en quoi est-ce nécessaire d’avoir un historique des décisions d’architecture ?

La première vertu des ADR est d’être un outil qui permet une traçabilité des décisions : à tout moment, quelque soit notre historique sur le projet, on peut comprendre pourquoi telle ou telle décision a été prise et s’il faut les revoir suite aux évolutions du contexte projet.

Cela permet ainsi de comprendre pourquoi la situation est ce qu’elle est aujourd’hui et d’avoir plus d’assurance pour faire des choix d’architecture qui peuvent remettre en cause les choix précédents. Plus de décision aveugle sur le fait de tout casser ou de tout garder en l’état, on peut prendre des décisions éclairées !

C’est également un outil utile dans un contexte de projet au long cours, transverses à plusieurs équipes : il permet d’avoir une mémoire des choix effectués. Il est important que les ADR soient accessibles au plus grand nombre, et notamment aux développeurs des différentes équipes ou services concernés.

Un effet de bord intéressant, c’est qu’en rendant explicite les décisions, leur contexte et leurs conséquences, cela amène à avoir une réflexion en amont sur le bien fondé de la décision et d’être pleinement conscient des conséquences positives comme négatives de cette décision.

De plus, en ancrant cette décision dans un contexte précis, il est plus facile de revoir l’ensemble des décisions à la lumière d’un changement de contexte, pour les déprécier et en prendre de nouvelles si nécessaire.

Enfin, les ADR constituent un support fort utile pour alimenter des revues d’architecture, pour préparer rétrospectives et REX d’un projet ou rédiger le postmortem d’un problème.

Quelles sont les parties constitutives d’un ADR ?

Il existe plusieurs écoles pour structurer un ADR, mais la version classique est en général constituée a minima des 4 parties suivantes :

• Titre : ADR 10 : Ecriture d'une brique batch séparée en C# pour convertir les documents Office
• Contexte dans lequel la décision d’architecture décrite dans ce document est prise
• Décision prise dans le cadre de l’ADR résumé en 1 ou 2 phrases.
• Conséquence(s) pour l’application, les développements, l’implémentation, etc. de cette décision

C’est un court fichier texte dans un format similaire à celui des modèles de conception de Christopher Alexander.

Chaque enregistrement décrit un ensemble de forces et de contraintes et une unique décision en réponse à ces forces et ces contraintes : la décision est le point central. Ainsi des forces et des contraintes spécifiques peuvent apparaître dans de multiples ADR : il est important, à l’image du principe SRP (Single Responsability Principle) en conception objet, qu’un ADR donné ne traite que d’une unique décision.

Il est primoridal que le contexte et les conséquences d’un ADR soient factuelles : ils ne doivent servir ni à régler ses comptes, ni à faire de la politique, ni à montrer que l’on n’est pas d’accord, ni à valoriser ou dévaloriser quelqu’un, etc. On vise au factuel et à l’objectivité, il faut avoir les éléments pour comprendre la décision et comprendre ses impacts. Une décision n’est ni bonne ni mauvaise, elle a un sens dans un certain contexte et un ensemble d’impacts qu’il est nécessaire de prendre en compte.

Quels sont les points importants à ne pas oublier ?

De mon point de vue, le contexte et les conséquences sont essentiels à un ADR qui perd grandement de sa valeur et de son utilité sans eux.

Mais au fait qui prend la décision ?

Cela va dépendre de votre organisation, de la manière dont vous travaillez avec votre ou vos architectes et de qui est concerné par la décision (un projet, une équipe, plusieurs équipes, l’entreprise).

La décision peut être prise de manière collégiale avec l’ensemble des parties concernées de près ou de loin par la décision ou bien être la seule responsabilité de la cellule architecture. Il y a bien sûr un continuum de situations intermédiaires. Dans tous les cas, il faut bien s’assurer que la décision soit bien communiquée à tous ceux qui sont impactés par elle.

Vous pouvez définir pour vos ADR un statut Refusé et les historiser également mais ce n’est pas une obligation. Cela peut être pertinent pour matérialiser qu’il y a eu débat sur une décision même si au final elle a fini par être rejetée.

Et si finalement la décision doit être changée ?

Un ADR a un statut qui sert exactement à cette fin. Si la décision n’est plus valable car le contexte a changé ou que les conséquences de cette décision ne sont plus souhaitables ou gérables dans le nouveau contexte, l’ADR en question sera dépréciée et un nouvel ADR documentant la nouvelle décision et son contexte pourra être écrit.

Il est important à mon sens que la décision qu’enregistre un ADR soit elle-même immuable : on change le statut de l’ADR, éventuellement on complète le contexte ou les conséquences mais on ne change pas la décision. Si on revient en arrière sur la décision, on déprécie l’ADR et on en écrit un nouveau qui fait référence à cet ADR déprécié (cela constitue tout ou partie du contexte du nouvel ADR).

C’est uniquement pour les décisions d’architecture ?

La traçabilité des décisions importantes n’est pas pertinente uniquement pour les choix d’architecture, et le format des ADR est en soit pertinent. On pourrait imaginer d’avoir une historisation de décisions métiers ou de décisions organisationnelles par exemple.

Un point important est que les ADR doivent être de la documentation utile. et ne documenter que les décisions significatives : il faut être au bon niveau de granularité et être d’accord entre les parties prenantes sur ce qui est important et doit être tracé. Intuitivement ce sont les décisions structurantes, c’est-à-dire les décisions qui sont plus difficiles et/ou plus coûteuses à modifier une fois prises.

C’est la logique des ADR, non comme Architecture Decision Record mais comme Any Decision Record. Mais vous pouvez, également utiliser dans ce cas un acronyme plus dédié, par exemple BDR (Business Decision Record) si cela concerne des décisions métier.

Et je peux faire ma propre variante des ADR ?

Evidemment ! Les ADR sont un outil qui se prête bien à une personnalisation : il faut être pragmatique et savoir adapter les outils que vous croisez pour qu’ils répondent au mieux à vos besoins. D’ailleurs, il existe déjà plusieurs variantes (Vous en avez quelques une listées ici).

En parlant de conséquences, quelles sont-elles pour un ADR ?

La mise en place des ADR n’est pas très coûteuse en elle-même et ne représente pas un gros risque : c’est un document court, rapide à rédiger qui ne demande pas de matériel ou logiciel particulier. Il s’insère dans un processus qui existe déjà, celui de la prise de certaines décisions, et n’ajoute qu’un faible surcoût dans ce processus.

Le ROI (Return On Investment) de la pratique se mesure sur le long terme si elle est effectuée de manière consistante.

Et tu aurais un exemple d’ADR sous la main pour rendre les choses plus concrètes ?

Oui bien sûr, j’ai mis un exemple d’ADR dans un dépôt sur GitHub.

Et tu aurais un exemple de mise en place d’ADR ?

Comme écrit un peu plus haut, les ADR ne sont pas prescriptifs d’une démarche spécifique. Néanmoins, il est légitime de s’interroger sur leur mise en place dans le cadre d’un projet. Il faut distinguer le cas d’un nouveau projet et d’un projet existant.

Il y a 2 axes à prendre en considération quand on met en place des ADR : un axe relatif au périmètre de la mise en place et un axe relatif au type de projet sur lequel on le met en place (nouveau projet ou projet existant).

Axe relatif au périmètre de mise en place

Est-ce une mise en place à l’échelle d’une entreprise, d’un projet ou d’une équipe ? Est-ce que c’est une pratique qui est testée dans le cadre d’un projet pour une adoption plus large si cela fait ces preuves ?

• Si la mise en place est à l’échelle de l’entreprise ou d’un projet multi-équipes, en toute logique c’est aux architectes (ou aux personnes assurant ce rôle) d’être les garants du suivi du processus.
• Si la mise en place est à l’échelle d’une équipe, il faut bien calibrer l’utilisation des ADR, afin de les écrire pour ce qui relève vraiment de choix d‘architecture sinon il y aura trop d’ADR pour des décisions mineures ou pour des choix de conception, donc pas au même niveau de granularité. Il est tout à fait possible d’avoir des enregistrements des décisions de conception mais ce ne sont plus des ADR (des DDR, Design Decision Record ?). Et dans tous les cas, il faudra que l’équipe fasse preuve de discipline et de constance dans la rédaction des ADR.

Axe relatif au type de projet

Sur un nouveau projet, il ne devrait pas y avoir de défis particuliers, il suffit de commencer à rédiger les ADR, pour toutes décisions structurantes. Une des difficultés est bien sûr de ce qu’on entend par structurante : il ne faut pas que l’équipe tombe dans le piège de ne pas être au bon niveau de granularité.

L’autre écueil à éviter est de ne pas être discipliné pour écrire les ADR et de n’en rédiger que quand on a le temps ou on y pense. Les ADR en soit ce n’est pas compliqué mais cela demande de la rigueur, de la constance et de la discipline à l’équipe pour que la pratique soit fructueuse. Le fait de mettre en oeuvre des ADR peut d’ailleurs être le premier ou un des premiers ADR !

Si c’est un projet que vous reprenez et qui utilise déjà des ADR, c’est relativement simple, il suffit de continuer à faire les ADR.

Si vous arrivez sur un projet sans ADR, comme pour un projet sans tests automatisés, ce n’est pas une raison pour ne pas commencer à les mettre en place. Cependant il y a un vrai challenge et un coût d’entrée ! La difficulté est que vous n’avez justement pas l’historique des décisions !

Le premier ADR pourrait être la aussi la mise en place des ADR, avec un contexte spécifique qui est celui d’une application legacy dans laquelle de nombreuses décisions n’ont pas été tracées. Si vous avez de la chance vous pouvez trouver dans d’autres documents de conception du projet des éléments donnant des indications sur les raisons de ces différents choix. Dans tous les cas, cela représente bien une partie du contexte dans lequel vous allez prendre vos décisions d’architecture actuelles.

De plus, si vous n’avez pas le contexte des décisions et leurs impacts, vous avez le produit de ces décisions sous les yeux : si l’application est une application Web monolithique en Java/Spring, c’est bien le produit de décisions prises à un moment ou un autre lors de la vie du projet. Vous ne savez pas pourquoi ces choix ont été faits, mais c’est bien une partie du contexte dans lequel vous avez à prendre vos décisions d’architecture maintenant et dans lequel elles auront des impacts divers.

Il est probable que dans un tel cas, la mise en place des ADR suscitera plus de frictions et un coût de mise en œuvre initiale plus important. Le plus gros risque, est qu’il y ait un abandon de la pratique avant même qu’elle puisse démontrer son intérêt.

Et si je souhaite creuser le sujet ?

Bien sûr, l’idéal est de prendre le temps de lire le billet original de Michael Nygard sur les ADR : Documenting Architecture Decisions. Si vous êtes allergiques à l’anglais, j’en propose une traduction en français.

L’article Sustainable Architectural Design Decisions donne une vision complémentaire aux ADR. Cet article s’intéresse surtout à la question de la durabilité des décisions d’architectures et des moyens qui peuvent être mis en œuvre pour prendre des décisions de conception durables. S’il ne préconise pas en particulier les ADR, il rejoint cette approche en prônant une documentation légère et simple. Il va cependant plus loin en mettant l’accent sur la traçabilité, en définissant des critères de durabilité des décisions et en proposant des lignes directrices pour atteindre cette durabilité des décisions d’architecture. On peut juste noter au passage que les ADR peuvent constituer les premières étapes pour la mise en place d’une démarche de ce type.

Les ADR sous la forme de Lightweight Architecture Decision Records sont mentionnés dans la partie Techniques du Technology Radar de ThoughWork dès Novembre 2016 (en Trial) jusqu’en mai 2018 (en Adopt).

Il est possible de trouver des ressources sur les ADR (dont plusieurs modèles). Par exemple, on peut citer :

• la page de l’organisation ADR sur GitHub, c’est vraiment le point de départ avec des nombreuses ressources et pointeurs.
• Les templates en Markdown que Joel Parker Henderson propose sur sa Page GitHub sur les ADR. D’ailleurs, sur ce dépôt il y a également de nombreux liens et conseils pour se mettre aux ADR.
• le format MADR, Markdown Architectural Decision Records.
• les MADR, Markdown Any Decision Records (c’est un sous-projet de l’organisation ADR sur GitHub)
• le format E-ADR (Embedded Architectural Decision Records).
• Sur Medium, “Doc SoC (aka ZIO)” propose plusieurs articles sur les ADR.

Je vous propose également des templates aux formats Markdown et AsciiDoc sur ce dépôt GitHub.

En conclusion

J’ai commencé à m’intéresser aux ADR en 2016/2017 (sachant que l’article de Michael Nygard datait de 2011). Je me rappelle qu’à l’époque la pratique n’était pas généralisée et je n’ai pas rencontré beaucoup d’architectes qui connaissaient la pratique. Par contre, en la présentant et en discutant la plupart en voyait l’intérêt.

Récemment, j’ai vu passer des missions pour des rôles d’architecte citant explicitement les ADR et j’ai participé il y a peu au DevFest Lille dans laquelle les ADR ont été directement cités dans plusieurs conférences. A ma grande satisfaction, je m’aperçois que la pratique a gagné du terrain.

Les ADR sont faciles et peu coûteux à mettre en place. Au prix d’une discipline et d’une constance rédactionnelle, ils fournissent un support très appréciable pour garder un historique et une traçabilité des décisions d’architecture prises. Ainsi ils permettent de ne pas perdre de vue les choix effectués, le contexte de ces choix et leurs conséquences, ce qui permet de prendre de nouvelles décisions plus éclairées. Il serait vraiment dommage de s’en priver.

Ce billet est basé sur un article que j’avais initialement publié sur mon blog personnel en 2020.

Remerciement

Je remercie mes collègues Thomas Verhoken et Anthony Tenneriello pour leur relecture attentive et leurs remarques sur ce billet.