Vous connaissez cette frustration de travailler sur un projet et de ne pas savoir pourquoi une décision technique a été prise ou de subir les conséquences d’une décision mal éclairée ? Eh bien, bonne nouvelle, les architectures decision record (ADR) sont là pour nous aider à documenter ces décisions cruciales. Je vais vous montrer comment les ADR peuvent transformer la documentation et la communication de vos décisions clés, tout en améliorant la collaboration au sein de votre équipe.
Qu’est-ce qu’un ADR ?
Un ADR, ou Architecture Decision Record, est un court document texte qui décrit une décision technique importante prise lors du développement d’un projet. Il s’agit de capturer les raisons qui ont conduit à cette décision, les alternatives envisagées, et les conséquences possibles de la décision.
Il n’existe pas de format unique pour les ADR. Les équipes peuvent adapter la structure d’un ADR en fonction de leurs besoins et de leurs préférences. Voici par exemple une structure d’ADR :
- Numéro (ou date) : Identifiant unique de l’ADR (par exemple, ADR-001) ou la date de création ;
- Titre : Un bref résumé de la décision ;
- Auteur : Le ou les auteurs de l’ADR, généralement les personnes impliquées dans la prise de décision ;
- Contexte : Description de la situation ou du problème qui a conduit à la prise de décision ;
- Décision : La décision elle-même, clairement énoncée ;
- Statut : Le statut actuel de l’ADR (par exemple, proposé, accepté, rejeté, abandonné, remplacé, etc.) ;
- Conséquences : Les conséquences positives et négatives de la décision, ainsi que les implications pour le projet ;
- Références : Liens vers des ressources externes, telles que la documentation, les articles de blog ou les discussions pertinentes pour la décision.
Prenons un exemple. Supposons que l’équipe de développement travaille sur une nouvelle application web et doit choisir un framework pour la réaliser. Trois options ont été identifiées comme possibles : React, Angular et Vue.js. Chaque framework présente ses propres avantages et inconvénients, et l’équipe doit évaluer chacun d’eux en fonction de critères tels que la facilité d’apprentissage, la flexibilité, la performance et la popularité. Nous pouvons écrire un ADR au format Markdown comme suit :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | # ADR-001 : Choix du framework pour notre application web - **Auteur** : John Doe - **Date** : 2023-05-05 ## Contexte Notre équipe travaille sur une nouvelle application web destinée à faciliter la gestion des projets internes. Pour développer cette application, il est nécessaire de choisir un framework parmi les trois options suivantes : React, Angular et Vue.js. ### Critères de sélection 1. **Facilité d'apprentissage** : Temps et effort requis pour apprendre le framework et être productif 2. **Flexibilité** : Possibilité d'adapter le framework à nos besoins et contraintes spécifiques 3. **Performance** : Rapidité et efficacité du framework en termes de temps de chargement et d'exécution 4. **Popularité** : Taille et activité de la communauté de développeurs, ainsi que la disponibilité des ressources (documentation, tutoriels, etc.) ## Décision Après avoir examiné les options en tenant compte de critères tels que la facilité d'apprentissage, la flexibilité, la performance et la popularité, nous avons décidé d'utiliser **React** pour notre application web. ### Pourquoi React ? 1. **Grande communauté** : React bénéficie d'une vaste communauté de développeurs, ce qui signifie un meilleur soutien et plus de ressources disponibles. 2. **Flexibilité** : React offre une grande flexibilité pour structurer et organiser notre application selon nos besoins spécifiques. 3. **Performance** : React est reconnu pour ses performances élevées grâce à sa méthode de rendu optimisée, le DOM virtuel. 4. **Écosystème riche** : Un grand nombre de bibliothèques et d'outils complémentaires sont disponibles pour étendre et améliorer les fonctionnalités de React. ## Statut Accepté ## Conséquences En choisissant React, voici les conséquences pour notre projet : - **Temps d'apprentissage** : Les membres de l'équipe qui ne sont pas familiers avec React devront investir du temps pour apprendre cette technologie. - **Meilleure collaboration** : Grâce à la popularité de React, il sera plus facile de recruter de nouveaux développeurs et d'obtenir de l'aide en cas de besoin. - **Maintenance simplifiée** : La grande communauté et la documentation abondante de React facilitent la maintenance et la résolution des problèmes. Pour aider les membres de l'équipe à se familiariser avec React, nous organiserons des sessions de formation et des ateliers. De plus, nous mettrons en place un processus de revue de code pour garantir que les meilleures pratiques sont respectées. ## Références - [Documentation React](https://reactjs.org/docs/getting-started.html) - [Enquête State of JS 2022](https://stateofjs.com/2022/frameworks/) |
Pourquoi utiliser des ADR ?
Les ADR offrent de nombreux avantages pour les équipes de développement lorsqu’il s’agit de documenter les décisions techniques importantes. Voici quelques-unes des raisons pour lesquelles il est bénéfique d’utiliser des ADR.
Transparence et communication
Les ADR fournissent un moyen clair et structuré de communiquer les décisions techniques au sein de l’équipe et avec les parties prenantes externes. En documentant les raisons derrière une décision et les alternatives envisagées, les membres de l’équipe et les parties prenantes peuvent comprendre les motivations et les facteurs qui ont influencé la prise de décision.
Traçabilité des décisions
Les ADR permettent de garder une trace des décisions techniques prises au fil du temps. Cela facilite la compréhension de l’évolution du projet et de son architecture, ainsi que l’identification des décisions qui peuvent nécessiter une réévaluation ou une mise à jour.
Apprentissage et amélioration
En documentant les décisions, les ADR encouragent la réflexion et l’analyse approfondie des choix techniques. Cela favorise un apprentissage continu au sein de l’équipe et peut conduire à des améliorations dans la prise de décision et les processus de développement.
Onboarding des nouveaux membres
Lorsqu’un nouveau membre rejoint l’équipe, les ADR servent de ressource précieuse pour comprendre l’histoire et la logique derrière les choix techniques du projet. Cela facilite leur intégration et leur permet de mieux comprendre et contribuer au projet.
Responsabilisation
Les ADR aident à responsabiliser les membres de l’équipe en documentant les décisions et en identifiant les personnes impliquées dans la prise de ces décisions. Cela favorise une culture de responsabilité et d’engagement envers les choix techniques.
En résumé, l’utilisation des ADR favorise une meilleure communication, une plus grande transparence et une prise de décision plus éclairée dans le développement de projets. Les ADR contribuent également à améliorer l’apprentissage au sein de l’équipe, à faciliter l’intégration des nouveaux membres et à encourager la responsabilisation.
Bonnes pratiques et conseils
Dans ce chapitre, nous aborderons les meilleures pratiques pour stocker et gérer les ADR, le format de rédaction à adopter et d’autres conseils pour tirer le meilleur parti de ces documents.
Où stocker les ADR ?
Les ADR sont généralement stockés dans le dépôt du projet, dans un répertoire dédié (par exemple, adr/ ou docs/adr/). Cela permet de les garder à proximité du code source et facilite leur consultation par les membres de l’équipe.
Format de rédaction
Le format Markdown est couramment utilisé pour la rédaction des ADR en raison de sa simplicité et de sa facilité de mise en forme. Les fichiers Markdown peuvent être facilement visualisés et édités dans la plupart des éditeurs de texte et des IDE, et peuvent être rendus sous forme de pages HTML pour une consultation plus agréable.
Conseils pour la rédaction des ADR
Voici quelques conseils pour rédiger des ADR de qualité :
- Utilisez un identifiant unique et des titres descriptifs : Chaque ADR doit avoir un identifiant unique (par exemple, ADR-001) ou une date, et un titre descriptif pour faciliter le suivi et les références croisées entre les ADR.
- Rédigez les ADR en temps réel ou peu de temps après la prise de décision : Documentez les décisions au fur et à mesure qu’elles sont prises ou peu de temps après, afin d’éviter la perte d’informations cruciales et de garantir l’exactitude des ADR.
- Soyez concis et clair : Les ADR doivent être courts et faciles à comprendre. Évitez les longs paragraphes et les phrases complexes. Utilisez des listes à puces, des tableaux et des en-têtes pour structurer le contenu et faciliter la lecture.
- Utilisez un langage neutre et factuel : Les ADR doivent présenter les faits et les arguments de manière objective, sans prendre parti. Évitez les jugements de valeur et les opinions personnelles.
- Documentez les alternatives et les conséquences : Lorsque vous présentez une décision, assurez-vous de documenter également les alternatives envisagées, les raisons pour lesquelles elles ont été écartées et les conséquences positives et négatives de la décision.
- Les ADR sont immuables, créez-en un nouveau en cas de changement de décision : Si une décision change ou évolue, créez un nouvel ADR pour documenter ce changement et référencez l’ADR précédent. Les ADR doivent être considérés comme immuables, c’est-à-dire qu’une fois acceptés, ils ne doivent pas être modifiés, excepté, bien entendu, pour changer leurs statuts.
- Utilisez des références : N’hésitez pas à inclure des liens vers des articles, des documentations ou d’autres ressources pertinentes pour étayer votre argumentation et faciliter la compréhension du lecteur.
- Assurez une revue régulière des ADR : Planifiez des revues régulières des ADR pour vous assurer que les décisions prises restent pertinentes et pour identifier les éventuelles mises à jour ou compléments nécessaires.
- Partagez les ADR avec les parties prenantes concernées : Les ADR doivent être accessibles à tous les membres de l’équipe et, si nécessaire, aux parties prenantes externes concernées. Cela favorise une meilleure compréhension des décisions et une communication plus transparente.
En appliquant ces bonnes pratiques et en stockant vos ADR de manière appropriée, vous pourrez tirer pleinement parti des avantages qu’ils offrent en matière de communication, de traçabilité et d’amélioration continue au sein de votre équipe de développement.
Petit aparté à propos des statuts
Comme précisé précédemment, une fois qu’un ADR est rédigé et accepté, il est considéré comme “immuable”, c’est-à-dire qu’il ne doit pas être modifié ou réécrit. Cette règle est essentielle pour maintenir la traçabilité des décisions techniques prises tout au long du projet.
Si, plus tard, cette décision est révisée ou remplacée par une nouvelle décision, au lieu de modifier l’ADR initial, un nouvel ADR est créé pour documenter ce changement. Le statut de l’ADR initial peut alors être mis à jour pour indiquer qu’il a été “remplacé” ou “déprécié”.
Ce processus permet de garder un historique clair et précis des décisions techniques prises, tout en montrant comment elles ont évolué au fil du temps. De cette façon, même si une décision change, la justification et le contexte de la décision originale restent préservés pour référence future.
Voici quelques exemples de statuts que vous pourriez trouver dans un ADR :
Proposé : La décision a été formulée mais n’a pas encore été adoptée ou rejetée. Elle est en cours de discussion ou d’examen.
Accepté : La décision a été approuvée et est actuellement mise en œuvre.
Rejeté : La décision a été refusée. Les raisons du rejet sont généralement documentées dans l’ADR.
Abandonné : La décision avait été acceptée à un moment donné, mais a depuis été abandonnée. Cela peut arriver si une nouvelle technologie plus appropriée apparaît, ou si la décision initiale s’avère ne pas convenir à l’architecture du système en cours de développement.
Remplacé : La décision a été remplacée par une nouvelle décision, souvent documentée dans un nouvel ADR.
- Déprécié : La décision technique documentée n’est plus considérée comme pertinente ou appropriée, en raison de l’évolution du projet ou de nouvelles informations disponibles.
Il est important de souligner que, bien que les ADR soient immuables, cela ne signifie pas que les décisions qu’ils documentent ne peuvent pas être modifiées. Les ADR sont conçus pour fournir une documentation et une justification des décisions prises à un moment donné, mais ils ne sont pas censés restreindre la capacité de l’équipe à réviser ces décisions à l’avenir. En d’autres termes, l’immutabilité des ADR concerne la documentation des décisions, et non les décisions elles-mêmes.
Pour finir…
Les ADR sont un outil essentiel pour documenter et communiquer les décisions techniques importantes prises lors du développement d’un projet. Ils permettent de garder une trace claire des raisonnements et des choix effectués, facilitant ainsi la compréhension et la collaboration au sein de l’équipe. En adoptant les bonnes pratiques de rédaction et en mettant en place une gestion efficace des ADR, vous contribuerez à améliorer la qualité de votre documentation technique et à renforcer la communication entre les membres de l’équipe.
N’hésitez pas à adapter la structure et le format des ADR aux besoins spécifiques de votre projet et de votre équipe. L’essentiel est de trouver une approche qui vous convienne et qui vous permette de tirer pleinement parti des avantages offerts par les ADR. Alors, commencez dès aujourd’hui à documenter vos décisions et à construire un historique précieux pour le futur de votre projet.
Je suis lead developer dans une boîte spécialisée dans l’univers du streaming/gaming, et en parallèle, je m’éclate en tant que freelance. Passionné par l’écosystème JavaScript, je suis un inconditionnel de Node.js depuis 2011. J’adore échanger sur les nouvelles tendances et partager mon expérience avec les autres développeurs.
Si vous avez envie de papoter, n’hésitez pas à me retrouver sur Twitter, m’envoyer un petit email ou même laisser un commentaire.
