Architecture Decision Record : on commence aujourd’hui

L’Architecture Decision Record (ADR), c’est comme le sexe chez les adolescents, tout le monde en parle, mais pas grand monde le fait. (Citation adaptée de Dan Ariely)

L’ADR est un journal de décisions prises par l’équipe de développement. Les décisions peuvent être : Quel type de bases de données, quelle architecture, quel langage, quelle modélisation, etc.

Les deux douleurs que nous constatons dans les équipes vis-à-vis des ADR sont : identifier quelles décisions tracer dans l’ADR et les rédiger.

Afin de résoudre ces deux douleurs, cet article vise à changer la perception des ADR et donner une méthode pour se mettre à les écrire.

Qu'est-ce qu'un Architecture Decision Record ?

L’ADR est un journal de chaque décision et un outil de facilitation très puissant. Les utilisateurs de l’ADR sont les membres actuels et futurs de l’équipe et parfois des cellules d’architecture transverses.

Il prend la forme suivante :

• Qui décide ?

• Quel est le contexte ?

• Quelles sont les options que nous avons identifiées ?

• Quels sont les avantages et inconvénients pour chaque option ?

• Quelle décision est prise et selon quels critères ?

• Quels sont les conseils récoltés au fil de discussions ?

• Quelles sont les conséquences de cette décision ?

Le tableau suivant présente l’intérêt de chacun de ces éléments à la fois à court terme et à long terme :

Cet outil permet d’éviter d'avoir la même conversation encore et encore. Ex : Maven vs Gradle, pytest vs unittest. Une fois que la décision est prise, si quelqu’un veut en rediscuter, renvoyez le vers l’ADR, s'il n’a pas d’autres arguments n’en parlez pas, s’il a d’autres arguments, vous pouvez en parler.

L’ADR vous permettra, dans quelques mois, de comprendre pourquoi une décision a été prise (au lieu du simple "l’architecture est la suivante" fourni par d'autres types de documentations).

Une décision peut n’avoir qu’une seule option. Il convient tout de même de la tracer pour voir plus tard qu’aucun autre choix n’avait pu être identifié.

Les développeurs sont rarement motivés par la rédaction de documentation, car elle n’est rapidement plus à jour. Dans le cas de l’ADR, il s’agit d’une documentation “événementielle” (c.-à-d. : il s’est passé cela ce jour-là) et non pas descriptive. Elle n'est donc jamais périmée.

NB : Pour aller encore plus vers une documentation toujours à jour, le lecteur peut s’intéresser au concept de living documentation.

Un exemple

- 📅 Date : 2022/01/11
- 👷 Décision prise par : Product Owner, Développeurs

Contexte

Les objets métiers ont un nom français, mais l'équipe de run sera anglophone.
La question est de savoir quelle langue utiliser dans notre base de code.

Options envisagées 💡

1. Français
    - ✅ Avantage : Nous utilisons les mêmes mots que les métiers, il est plus facile de faire des revues de code avec eux. 
    - 🚫 Inconvénient : L'équipe de run ne le comprend pas.

2. Anglais
    - ✅ Avantage : L'équipe d'exécution le comprendra 
    - 🚫 Inconvénient : Les métiers devront traduire, et nous pourrions avoir un peu plus de réflexion à faire en codant.

Décision 🏆

Nous choisissons l'anglais, car il est plus simple de traduire de l'anglais vers le français quand on connaît les deux langues que du français à l'anglais quand on ne connaît pas le français.

Conséquence

Nous décidons de mettre en place un dictionnaire de traduction avec code pour aider le processus de traduction.

Le template utilisé pour cet exemple peut être retrouvé sur GitHub, des exemples de décisions plus complexes sont également proposés.

NB : Certains aiment introduire une notion de statut pour une décision. Est-elle en cours de rédaction, acceptée, suspendue, etc. ? Il est possible de traiter cela en ajoutant l’information dans le template ou via la stratégie de gestion de branche : Une décision en cours est sur une feature branch. Lorsqu’elle est acceptée, elle est mergée sur la branche main.

L’ADR : un outil de facilitation de prise de décision

En plus d’être une documentation, l’ADR est un outil de facilitation puissant.

Lorsque vous avez des discussions techniques, initiez une nouvelle décision et rédigez-la pendant la discussion. Cela permettra de ne pas oublier d'idées ou d'arguments et de vous assurer que tout le monde comprend bien ce dont vous discutez.

Toute conversation qui dure plus de 5 minutes ou que vous avez déjà eue mérite d’être tracée dans l’ADR.

Cet outil permet de prendre des décisions de manière synchrone et asynchrone. De manière synchrone en remplissant au fur et à mesure le template partagé sur un écran. De manière asynchrone en commençant par A qui discute avec B, puis A avec C, … jusqu’à ce que A soit à même de prendre une décision.

Le template ne se remplit pas nécessairement de manière linéaire, au fur et à mesure, vous comprenez mieux le contexte, vous pouvez mieux challenger les idées précédentes.

Enfin, avant de prendre une décision, au vu des différents choix, il est parfois pertinent de réaliser un spike (une expérimentation) pour tester une hypothèse. Par exemple, tester si la base PostgreSQL peut tenir la charge de 400 écritures secondes ou non.

Le cycle de vie d’une décision

Figure : Le cycle de vie d’une décision

Nous l’avons cité, la décision est prise en suivant un processus de discussions, d’expérimentations puis de décision. Une décision peut éventuellement rendre caduque une décision passée. Cependant, ne changez pas la décision précédente, mettez-la à jour. Soit en continuant d’écrire à la suite du fichier, soit en créant un nouveau fichier qui fait référence à la décision précédente et en ajoutant un statut “Déprécié” sur la décision qui n’est plus valable.

Dans ce diagramme, nous avons intégré une étape de prise de conseils auprès d’architectes afin qu’ils aiguillent l'équipe vers les meilleurs choix en fonction de leur expérience, des projets passés et des standards de l’organisation.

En termes de gestion de version, il est possible de faire :

• Une PR/MR d’ADR seul, puis une ou plusieurs PR de modification de code lorsque les modifications sont importantes.

• Une PR/MR atomique qui contient à la fois la modification et l’ADR, cela lorsque les modifications sont peu volumineuses.

Pour enfin les écrire : faire des ADR as-code

Plutôt que de mettre les ADR dans un espace Confluence ou un document Word partagé, nous recommandons de faire des ADR as-code. Sous forme de fichier Markdown (.md).

Nous recommandons cela afin de minimiser le coût de lecture / écriture. Les principaux scribes / lecteurs d’ADR connaissent idéalement bien la base de code (pour prendre des décisions pertinentes). As-code, l’ADR est proche des outils que nous utilisons quotidiennement et il n’est pas nécessaire d'ouvrir un autre outil pour rédiger une nouvelle décision.  Lorsqu’ils sont sur confluence, il faut ouvrir son navigateur web, se souvenir d'où l’ADR est rangé, etc.

Ensuite cela permet d’utiliser les mêmes mécanismes que le code : PR/MR, refactoring, gestion de version. Cela permet de garantir l’historisation des versions, la revue par les pairs, …

Une façon de le faire est de laisser la PR/MR d’ADR ouverte pendant quelques jours pour que tout le monde puisse la réviser. Sur des PR de code qui méritent un ADR en tant que relecteur, vous pouvez demander à ce que le développeur ajoute un ADR pour tracer ces choix.

Enfin, l’ADR as-code est publiable dans le wiki Azure Devops, les pages GitLab ou GitHub ou même confluence en ajoutant une étape à votre CI.

Pour minimiser encore plus le coût d’entrée, commencez par mettre l’ADR dans un de vos repository de code existant plutôt que dans un nouveau pour le garder plus proche de vous. Le back est souvent un bon candidat. Vous pourrez l’extraire une fois que vous avez pris l’habitude dans un repository dédié à la documentation. Dans tous les cas, il convient d’avoir un seul ADR pour tous vos repository et non pas un ADR par repository, si besoin, vous pourrez organiser vos décisions par dossiers thématiques.

Figure : Proposition d’organisation de l’ADR dans un repository de code

Je commence par quoi ?

L’important est de commencer à écrire vos décisions, de prendre l’habitude, puis vous pourrez améliorer au fur et à mesure vos templates.

En début de projet, vous devez tracer au moins 1 décision par semaine, dans la suite peut-être une par sprint. Si vous en tracez moins, vous êtes probablement en train de prendre des décisions non conscientes : une partie de l’équipe n’est sans doute pas au courant des décisions et vous ne mesurez pas l’impact de celles-ci.

Les 3 premières décisions sur tous mes projets sont :

1. Faire des ADR

2. Coder en français ou en anglais

3. Coder en architecture hexagonale

Les décisions suivantes peuvent être avoir un code fonctionnel ou orienté objet, la façon de gérer le cache, le choix de base de données, mettre telle partie du code dans l’ETL ou dans le backend… Dans les projets embarquant une brique de Data Science, il est également possible d’intégrer les décisions de DS : quelles variables, quel modèle, etc.

Vous remarquez que j’ai un sens assez souple du mot Architecture, nous pourrions même oublier le A de ADR et parler uniquement de Décision Record.

Même si votre projet a commencé depuis un moment, vous pouvez commencer les ADR maintenant : en traçant toutes les nouvelles décisions et en traçant a posteriori les décisions passées. En ajoutant par exemple une phrase “Cette décision est tracée quelques mois a posteriori, les arguments écrits peuvent donc différer un petit peu de ceux que l’on avait au moment de la décision”

Niveau suivant : Intégrer des diagrammes as-code pour illustrer vos ADR

Il existe de nombreux outils pour rédiger des diagrammes as-code tel que mermaid ou  plantuml l’intérêt est à nouveau de pouvoir versionner, revoir les diagrammes produits.

De plus, lorsque vous voulez modifier un diagramme, il n’est plus nécessaire de retrouver où est-ce qu’il avait été initialisé (dans Miro, PowerPoint ou Draw.io), voire comme souvent le refaire de 0, car on a plus qu’une capture d’écran. Avec un diagramme as-code, il suffit de modifier le code.

Le diagramme de cycle de vie d’une décision a été rédigé avec mermaid, il est généré à partir du code suivant :

flowchart LR
   P[Problème \n technique] --> N[Initialisation \n de décision]
   N --> Di[Discussions]
   Di --> C[Prise de conseils \n auprès d'architectes]
   C --> Di
   Di --> De[Décision]
   De -.-> DP[Dépréciation de \n décisions passées]
   De --> I[Implémentations]
   I -.-> P
   Di -.-> E[Expérimentation]
   E -.-> Di
   NB[Nouveaux \n besoins] --> P

Il est possible de produire également des diagrammes de type C4 pour les schémas d’architecture. Toujours dans le même GitHub d’exemple, cet exemple propose des diagrammes de séquence pour illustrer de manière plus avancée la capacité des outils de diagrammes as-code.

Ainsi versionné, il n’y a plus besoin de se poser la question de quel diagramme va avec quel version du code, et quelle version de l’ADR, l’historique Git vous permettra de retrouver cela. C’est d’ailleurs très pratique si vous souhaitez réaliser une présentation qui montre l’évolution de votre architecture, vous n’aurez “qu'à” ressortir l’historique Git.

Conclusion

• L’ADR n’est pas qu’un outil de documentation, c’est également un outil de facilitation.

• Avoir un ADR as-code en markdown permet de l’intégrer au quotidien des développeurs et maximiser les chances qu’ils en écrivent.

• Pour commencer, tracer dans l’ADR toutes les décisions prises dans le projet, même la plus petite. Dans un second temps, vous pourrez challenger. Le plus important est de s’y mettre.

• L’ADR est une documentation événementielle, elle n'est donc jamais périmée.

• Ne pas avoir d’ADR c’est prendre le risque de prendre des décisions non conscientes.

Pour aller plus loin :

• S’intéresser aux façons de faire passer à l’échelle les prises de décisions d’architectures : https://martinfowler.com/articles/scaling-architecture-conversationally.html

• Lire cet article par Michael Nygard https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

• Il existe des outils tels que adr-tools pour automatiser certaines choses, mais ils ne sont pas du tout obligatoires.

Remerciement : Mehdi Houacine, Touraya El Hassani, Léa Naccache, Steeve Descapentries, Emilien Guilmineau, Christian Fauré, David Sliocini pour leurs relectures.