Définition des ADRs
Les ADRs (Architecture Decision Records) sont des fichiers qui documentent les décisions architecturales qui ont été prises au cours du développement d'un logiciel ou d'un système d'information (SI). Ils sont destinés à être facilement trouvés et compris par toutes les parties prenantes (développeurs, testeurs, responsables produits...) mais également par les futurs collaborateurs.
En pratique, cela se traduit comment ?
Si vous avez une certaine expérience dans le domaine du développement, vous avez probablement déjà été confronté à une décision d'architecture passée qui vous semblait dépourvue de logique. Vous vous êtes sûrement irrité contre ceux qui ont participé à cette décision, qui, malheureusement, ne font plus partie de l'organisation. Il est important de se rappeler que le système d'information d'une entreprise et l'environnement dans lequel il évolue sont constamment en mutation, à l'image d'un lit de rivière qui se transforme au fil des générations. Une décision qui était judicieuse à un moment donné peut ne plus l'être par la suite. Sans un résumé du contexte, de la situation et des options disponibles à l'époque, il est impossible de comprendre les contraintes auxquelles étaient confrontés vos prédécesseurs. Nous devons donc nous efforcer de ne pas juger le passé à travers le prisme du présent, un biais connu sous le nom de rétrospection. Pour nous aider dans cette tâche difficile, les ADRs représentent un outil précieux.
Un peu d'histoire :
Le terme ADR (Architecture Decision Record) a été introduit pour la première fois en 2009 par Michael Nygard dans son livre "Release It!". Bien que l'idée elle-même ne soit pas nouvelle, il n'existait pas de standard pour l'enregistrement des décisions architecturales avant cette date.
De façon plus générale :
L'enregistrement des décisions architecturales relève de ce que l'on appelle la gestion des connaissances techniques ou Architecture Knowledge Management (AKM). C'est une discipline qui vise à capturer, organiser, partager et réutiliser les connaissances architecturales d'une organisation. Elle revêt de multiples formes, dont les ADRs, qui ne représentent qu'une facette de sa complexité.
Les intentions derrière ce pattern sont :
- Améliorer la prise de décision en fournissant aux architectes et aux développeurs un accès facile aux informations pertinentes,
- Réduire les risques en évitant de répéter les erreurs du passé,
- Accélérer l'innovation en favorisant la collaboration et le partage d'idées,
- Augmenter la valeur de l'architecture en la rendant plus visible et accessible à tous.
L'AKM est donc un investissement stratégique qui permet aux organisations de tirer le meilleur parti de leur architecture.
Anatomie d'un ADR :
Mais revenons à des considérations plus pragmatiques. Un ADR doit être un document concis et facile à écrire afin de réduire, autant que possible, le coût de la rédaction. Les obstacles au passage à l'action doivent être minimisés pour que le plus grand nombre de collaborateurs puisse s'impliquer. Quant à la structure d'un ADR, elle doit coïncider avec vos attentes et votre contexte pour être parfaitement adaptée à vos besoins.
Le schéma suivant, qui est un exemple de la structure d'un ADR, présente un agencement que j'ai eu l'opportunité de mettre en place pour répondre aux problématiques spécifiques d'un de mes clients. Vous êtes libre de réutiliser cet agencement tel quel, ou de l'ajuster selon vos besoins.
Quelques bonnes pratiques :
Pour vous aider à rédiger des ADRs efficaces et pertinents, voici une liste de bonnes pratiques à suivre :
- Soyez clair et concis. Les ADR doivent être faciles à comprendre, même pour les personnes qui ne sont pas impliquées dans le projet.
- Soyez atomique. Un ADR doit contenir une seule décision pour faciliter l'arbitrage, maintenir l'intérêt du lecteur et réduire l'effort de rédaction.
- Incluez le contexte et les considérations. Les ADR doivent expliquer pourquoi une décision particulière a été prise.
- L'ADR doit être autoporteur. Le lecteur ne doit pas avoir à consulter plusieurs documents pour comprendre les tenants et aboutissants de la problématique.
- Soyez transparent sur les conséquences. Les ADR doivent identifier clairement les conséquences positives et négatives d'une décision, afin d'améliorer la prise de décision.
- Construire un contexte en entonnoir. Commencez par les informations les plus générales et progressez vers les plus spécifiques.
- Proposer plusieurs options. Il est rare qu'une seule stratégie soit viable. Listez plusieurs solutions possibles, en détaillant les avantages et les inconvénients de chacune.
Rendez-vous dans un prochain article pour en apprendre plus sur la mise en pratique des ADRs !
