TECH | Architecture decision record
Architecture Decision Records (ADR) est une technique méconnue dans la palette de la documentation vivante, elle permet de centraliser et rendre explicite un ensemble de décisions d’architecture prises au fil du temps, capturant le contexte et leurs alternatives possibles. Elle complète très bien la documentation par le code quand ces décisions concernent l’architecture évolutive de votre projet.
Un ADR1 peut être local (au sein d’un service), ou global (au sein d’une SI).
- Pourquoi choisir Quarkus ?
- Pourquoi implémenter une solution in house ?
- Pourquoi choisir ce partenaire de paiement externe plutôt qu’un autre ?
Comme nous le verrons, un ADR tient sa force de la transparence et de la collaboration.
Nous envisagerons également une utilisation possible en dehors de la Tech.
Il y a toujours une raison de choisir
Une décision part d’un raisonnement conscient ou inconscient, que ce soit une contrainte managériale, une paresse d’explorer plusieurs pistes, une habitude, ou une étude.
Le but de l’ADR est de capturer ce raisonnement sous la forme d’un log (Decision Record) ayant pour propriétés:
- d’être daté
- d’être immuable
- d’être révisable
- d’être traçable
- d’être contextualisé
- d’être explicite
- d’être approuvé par au moins un pair
La force des Decision Records
Les décisions d’architecture que vous prenez n’impactent pas que vous. Elles impactent la team actuelle, les futurs développeurs mais aussi les personnes externes aux projets.
- Combien d’équipes techniques ont dû être reconstruites de zéro suite à des démissions massives ? Les gens partent, les artefacts des décisions restent.
- Combien de fois vous a-t-on dits: “Nous avons déjà expérimenté ça dans le passé, je ne me rappelle plus pourquoi, mais ça n’a pas marché”. Les gens restent, la connaissance se perd.
- “Lors de notre audit nous avons découvert X et Y, pouvez-vous expliquer les choix qui ont amené à cette décision ?”
En systématisant la rédaction de Decision Record vous vous forcez de partir de l’espace du problème avant d’entrer dans l’espace de solutions (expliciter pourquoi avant d’explorer le comment).
En systématisant la revue par au moins un pair, vous vous assurez que le choix pris est partagé et compris par d’autres, que le contexte est juste, que des alternatives ont été explorées. Qu’un futur développeur sera dans la capacité de comprendre cette décision.
Remarquez les similitudes flagrantes avec le développement. Ce n’est pas pour rien que la plupart des ADR sont en fait des repositories git, où chaque décision est un commit, qu’une proposition de décision ou une révision de décision est une pull request.
Il est intéressant de constater que la plupart des exemples d’ADR sur github ont pour première decision record: adopter ADR. On utilise la technique pour valider la décision sur la technique.
Si le process est correctement suivi, le fait même de valider l’adoption de la technique doit passer par une étape de mise en contexte, d’explicitation et d’approbation.
Les faiblesses des Decision Records
Comme toute technique de collaboration basée sur le transfert de connaissances, elle rencontre des limitations. Faisons un petit tour d’horizon des faiblesses et des moyens de les contrer.
Lourdeur d’écrire un décision record
Ce n’est pas pour rien que Thoughtwork parle de “Lightweight Architecture Decision Records”, le but est de trouver un format de decision record simple à écrire. La forme (Markdown par exemple) peut être simplifiée, mais qu’en est-il du fond ?
Complexité de définir un décision record
Comme pour beaucoup de choses, il s’agit de définir les caractéristiques définissant la qualité d’une décision, permettant de maximiser sa valeur tout en maintenant un certain pragmatisme.
Passez le plus de temps possible à définir les propriétés que vous souhaitez atteindre. Le plus souvent, des solutions émergeront d’elles-mêmes.
Si plusieurs solutions ressortent, n’ayez pas peur de choisir une solution et d’essayer, il n’existe pas d’architecture parfaite, si vous avez défini et documenté les propriétés que vous souhaitez obtenir en amont vous avez fait un excellent travail d’architecture, le choix final sera alors une prise de risque mesurée.
Ownership
Voilà le mot est sorti. Qui est responsable de l’ADR ? Tout le monde ? Mais si c’est tout le monde ce n’est personne. L’architecte ? Il n’y en a pas toujours, et il n’est de toute façon pas omniscient.
Ici on pose le doigt sur le problème plus large de la documentation, quand ce n’est pas une documentation par le code. En début d’article je vous ai écrit “Architecture Decision Records (ADR) est une technique”, en réalité c’est une discipline.
Cette documentation doit rentrer dans un cadre de definition of done, au même titre qu’une documentation d’API rest, ou de librairie.
Au-delà de la Tech
Il n’y a pas que les dévs qui ont des problèmes de décisions implicites, oubliées ou incomprises. Prenez n’importe quelle équipe de votre boîte avec un certain turnovers et vous entendrez le même discours que dans la Tech.
- Pourquoi avoir choisi Salesforce comme outil CRM ? Il existe des solutions plus performantes et moins chères !
- Pourquoi le schéma comptable a-t-il été conçu ainsi ?
- Pourquoi a-t-on décidé la refonte complète de l’UI/UX du site web ?
- Pourquoi avoir changé l’organigramme de la société en 2016 ?
- Pourquoi avoir changé de business-modèle en 2017 ?
Cette discipline a une portée plus grande que la Tech, comme toute technique/discipline elle peut évoluer pour être réutilisée et adaptée à d’autres secteurs que celui qui l’a popularisé.
Maintenant, je m’en vais remplir mon Life Decision Record en expliquant pourquoi j’ai décidé d’écrire un article sur ADR.