Architecture et documentation : les ADRs

Les systèmes sur lesquels nous travaillons évoluent dans le temps. Cette évolution s’applique également à leur architecture, la documentation de l’architecture se doit donc d’y être adaptée. C’est la problématique à laquelle se proposent de répondre les Architecture Decision Records, ou ADRs.

Cet article a pour objectifs de vous aider à comprendre ce qui définit un ADR et de vous donner quelques clés pour la mise en place de ce nouveau mode de documentation.

C’est quoi, un (bon) ADR ?

ADR est l’acronyme de « Architecture Decision Record », qu’on pourrait traduire en français comme le compte-rendu d’une décision d’architecture.

Une décision d’architecture peut être définie comme la réponse à une exigence fonctionnelle ou non-fonctionnelle qui affecte la qualité du système. En bref, pour paraphraser Martin Fowler, ce sont les décisions qui concernent ce qui est essentiel, celles qui vont façonner votre système.

« Architecture is about the important stuff. Whatever that is. »

— Martin Fowler

L’ensemble des ADRs d’un projet constitue le decision log, un journal des décisions d’architecture.

Pour comprendre pourquoi documenter les décisions d’architecture est nécessaire, prenons deux exemples :

Dans un premier cas, l’équipe doit choisir un outil. Alors qu’une solution semble meilleure sur tous les plans, un prototype a montré qu’elle ne répondait pas à l’un des besoins critiques pour le produit. En toute logique, un nouvel arrivant sera tenté de remettre en cause ce choix, ce qui aboutira à du temps perdu voire à l’introduction de non-conformités dans le produit.
Dans un second cas, l’équipe rencontre un problème qui demanderait la refonte d’une partie importante de l’application à quelques semaines d’une période durant laquelle la stabilité du produit est critique. Étant donnée la période de la décision, une solution favorisant la stabilité à court terme aux dépens de la maintenabilité est adoptée. Au moment où la décision est prise, il est établi qu’elle devra être remise en cause à la suite de cette période critique. Mais en l’absence de documentation, il existe un risque que l’équipe n’ose pas la remettre en cause, en estimant que ce choix était certainement justifié.

Bref, en l’absence des éléments qui ont justifié une décision, celle-ci peut être remise en cause ou acceptée aveuglément. Dans un cas comme dans l’autre, les conséquences seront néfastes.

Considérer la passation orale comme une réponse suffisante à cette problématique est illusoire : après quelques mois, même la personne qui a pris la décision n’aura au mieux qu’un souvenir altéré du contexte qui a justifié son raisonnement et des conséquences envisagées à l’époque.

Critères d’évaluation

L’utilité des ADRs peut être jugée à l’aune de plusieurs critères :

L’adoption : Un decision log que personne ne consulte n’a aucune valeur.
La véracité : Les informations présentées doivent refléter la réalité sans ambiguïté. Cela implique notamment que les rédacteurs peuvent mettre à jour l’information simplement. En effet, si les lecteurs se considèrent susceptibles d’être induits en erreur par des informations imprécises ou obsolètes, le decision log ne sera pas consulté et il n’a donc aucune valeur.
L’historique : Par définition, un decision log consiste en un historique des décisions d’architecture. Cela permet d’assurer le suivi des décisions et apporte des informations nécessaires à la compréhension d’un contexte dans sa globalité.

Rôle

Comme on l’a déjà vu, le rôle des ADRs est de documenter les décisions d’architecture.

Malgré tout, il peut s’avérer tentant d’utiliser ces documents également comme un support au processus de prise de décision. C’est une direction que prennent certains modèles, de manière plus ou moins assumée.

De mon point de vue, ce n’est pas une bonne chose. D’une part, alors que la documentation après coup permet d’aller à l’essentiel, la discussion apporte un niveau de détail important, ce qui rend le document indigeste et moins pertinent dans son utilisation dans la durée. Et surtout, la prise de décision ne justifie pas l’utilisation de documents, dans le sens où elle a lieu à un moment donné et nécessite de la communication avant tout. Cette communication n’est pas toujours aisée, mais répondre à des difficultés de communication en imposant la lourdeur de nouveaux processus et documents revient à en oublier l’aspect humain.

C’est pourquoi il me semble important de garder à l’esprit l’objectif des ADRs et de ne pas en dévier. Une décision ne sera ainsi pas documentée avant qu’un consensus soit trouvé ou tant que sa mise en œuvre semble irréaliste.

Principes de base

Quelques principes permettent de définir un bon ADR quel que soit le modèle utilisé :

Léger : Si la rédaction de documents longs et aux formalismes complexes est envisageable à un moment donné d’un projet, le temps qu’elle nécessite aura tendance à décourager l’équipe dans la durée. C’est pourquoi un bon ADR est léger. Il se concentre sur les informations essentielles d’une décision afin de faire gagner du temps aussi bien à son rédacteur qu’à ses lecteurs.
Partagé : Les informations sont accessibles facilement aux personnes qui en ont besoin. Cela inclut les décideurs, mais surtout les personnes en charge de la concrétisation des décisions.
Immuable : Afin d’être considéré comme fiable, le decision log doit faire apparaître clairement toute modification dans les décisions qui le constituent. Pour faciliter cela, le contenu d’un ADR est considéré comme immuable, à l’exception de son statut, qui permet d’identifier si la décision est toujours d’actualité, amendée, remplacée par une autre décision, etc.
Justifié : Un bon ADR fournit les informations pertinentes pour comprendre une décision et la remettre en cause si nécessaire. Il s’agit en particulier des éléments de contexte dans lequel la décision a été prise, du raisonnement qui a amené à cette décision et des éventuelles conséquences anticipées.

Ça contient quoi, un ADR ?

Les différents modèles de documents disponibles proposent des niveaux de détails différents et un certain nombre d’éléments supplémentaires qui vont orienter l’usage du document. Toutefois, on peut identifier un socle commun, qui correspond aux informations essentielles.

Titre

Un ADR doit être identifiable facilement par un titre.

La numérotation des ADRs de manière unique et séquentielle facilite la définition de références.

Date

La date de création de l’ADR constitue un élément du contexte. Elle permet également d’ordonner le decision log.

Statut

Le statut permet de déterminer où se trouve une décision par rapport au cycle de vie défini de manière globale. Il s’agit du seul élément de l’ADR qui est susceptible d’évoluer dans le temps.

Le diagramme ci-dessous présente le cycle de vie proposé par Michael Nygard.

Catégorie

Certains modèles proposent la définition d’un champ pour la catégorie, qui permet de regrouper les décisions pour en faciliter l’accès.

Décision

En toute évidence, la décision elle-même doit être énoncée sans ambiguïté. C’est un élément nécessaire car la concision nécessaire à la définition du titre ne permet pas nécessairement d’y inclure l’ensemble des spécificités de la décision.

Contexte

Le contexte d’une décision comprend plusieurs éléments :

Le problème rencontré : pourquoi cette décision s’est-elle avérée nécessaire ?
Les contraintes pertinentes dans le cadre de cette décision.
Les hypothèses qui ont amené à cette décision.

Les éléments de contexte doivent être pragmatiques : ils peuvent inclure des éléments stratégiques tels que les priorités métier, mais aussi des éléments organisationnels tels que la composition de l’équipe, les problèmes relationnels, etc.

Conséquences

Toute décision est un compromis : si quelque chose est évident, indiscutable, il n’y a pas de décision à prendre et donc pas d’ADR.

Les conséquences positives comme négatives doivent être clairement exprimées. Ces conséquences constituent des opportunités et des risques. Au moment de la rédaction de l’ADR, exprimer clairement ces opportunités et ces risques encourage à décider d’actions appropriées, qui doivent également être documentées. Ceci permettra à un lecteur futur d’estimer si certaines conséquences n’ont pas été anticipées, auquel cas la décision sera vraisemblablement remise en cause.

Justification

La justification de la décision est un élément qui n’est pas formalisé de manière explicite par tous les modèles d’ADRs, mais souvent diffus dans l’énoncé de la décision elle-même, dans son contexte ou dans ses conséquences.

Définir une partie dédiée est particulièrement pertinent pour une décision qui est la conclusion de la comparaison fine de plusieurs alternatives, par exemple dans le cadre du choix d’un outil. Mais si la définition des critères d’évaluation et l’évaluation de la conformité de chaque solution sont utiles dans certains cas spécifiques, imposer un formalisme aussi lourd pour toutes les décisions nuirait à la légèreté du document.

Quoi qu’il en soit, il est important que la justification de la décision soit précise et factuelle.

Références externes

Lors de la mise en place des ADRs, la dispersion et la duplication de l’information sont deux risques importants. Pour y faire face, la définition de références dans un ADR est un enjeu majeur. Il peut s’agir de références vers d’autres ADRs, vers d’autres documents, vers des exigences fonctionnelles, vers des articles… Ces liens doivent permettre d’accéder au contenu correspondant sans présupposer d’une connaissance préalable du contexte de la part du lecteur.

Et en pratique, alors ?

Le format

La mise en place d’ADRs ne contraint pas à l’utilisation d’un format en particulier, à partir du moment où celui-ci permet de répondre aux différents critères d’évaluation d’un bon ADR tel que vu plus tôt. Par exemple, il est tout à fait possible d’entreposer des ADRs dans un Wiki, sous réserve que celui-ci offre un historique clair et lisible.

Malgré tout, la tendance générale est plutôt à l’utilisation de fichiers dans des formats minimalistes, en particulier le Markdown, et partagés par le biais d’un système de versioning tel que Git. L’utilisation de Git a en effet pour avantage de mettre les décisions là où les gens qui doivent les prendre en compte sont le plus susceptibles de les trouver, c’est-à-dire à côté du code source de l’application.

L’outillage

Un des principaux intérêts des ADRs résidant dans la simplicité de leur mise en œuvre, une grande partie de l’outillage proposé n’a qu’un intérêt anecdotique.

Notons quand même les outils de mise en forme du decision log (par la génération d’un menu avec ADR log ou sous forme de site web avec ADR viewer), qui peuvent faciliter le partage avec des non-développeurs.

Les modèles

Il existe de nombreux modèles de documents. Les plus anciens, tels que les tableaux d’UMF proposés par IBM (1998) ou le modèle de Tyree/Akerman (2005), se veulent exhaustifs (respectivement 13 et 14 champs) et sont par conséquent trop lourds pour être considérés comme pertinents par rapport à nos objectifs.

À l’inverse, le modèle le plus connu, à l’origine de la résurgence des ADRs, est celui qui a été proposé par Michael Nygard en 2011. Son succès est lié à sa simplicité (5 champs). Il en existe de nombreuses variantes qui apportent plus de détails pour guider davantage le rédacteur. Pour certains, cela conduit à une orientation particulière à certains usages (analyse des coûts, qualité, etc.). Une variante récente (2018), MADR, pour Markdown Architecture Decision Record, propose un contenu similaire au modèle de Michael Nygard enrichi de champs optionnels utilisables selon le type de décision, ce qui permet de bénéficier de directives tout en conservant une liberté qui aide à limiter le contenu à l’essentiel.

Les conventions

Une fois le format et le modèle choisis, il reste quelques conventions, qui tiennent du détail, mais qu’il est préférable de définir avant la mise en place des ADRs :

Dans quel dossier mettre les ADRs ? Un dossier comme /doc/adr, dans le projet qui contient le code source, est généralement utilisé.
Comment nommer vos fichiers ? Le nom d’un ADR est généralement composé de son numéro et de son titre, en minuscules et séparés par des tirets (0185-deployer-les-applications-java.md). Le numéro est défini sur quatre chiffres pour que les fichiers soient naturellement triés.
Quelle formulation utiliser pour vos titres ? Michael Nygard propose l’utilisation de phrase nominales (ADR 1 : Déploiement des applications Java) tandis que Joel Henderson lui préfère l’utilisation de tournures impératives (Déployer les applications Java).
Des catégories sont-elles nécessaires ? Cela dépend avant tout du périmètre couvert par les ADRs : si on anticipe un nombre de documents important, définir des catégories peut s’avérer pertinent.
Quel est le cycle de vie d’un ADR ? Le cycle de vie proposé par Michael Nygard (voir plus haut) a le mérite de répondre simplement à la plupart des cas, mais des ajustements peuvent être nécessaires dans certains contextes spécifiques.

L’emplacement

Les exemples d’ADRs montrent généralement un module logiciel unique sur un dépôt de code unique. Mais en entreprise, les modules logiciels sont généralement nombreux, ce qui pose la question du mono-dépôt face au multi-dépôts.

Tant qu’un dépôt de code unique est utilisé dans l’ensemble de l’entreprise, les ADRs peuvent être placés à la racine du dépôt et s’appliquer à l’ensemble des modules logiciels.

Par contre, si l’entreprise dispose d’applications qui se veulent clairement distinctes et réparties sur plusieurs dépôts de code (on pensera par exemple à une architecture en microservices), il existe nécessairement des décisions d’architecture transverses à ces applications, à commencer par la décision même d’effectuer ce découpage ! Il est par conséquent nécessaire de choisir (ou de créer) un dépôt en charge de contenir les décisions globales à l’entreprise. Les décisions propres à une application seront quant à elles entreposées dans le dépôt qui lui est spécifique.

Quelques exemples

Un dépôt d’exemples d’ADRs en français a été créé spécifiquement pour cet article. Il présente des types de décisions variés (conception, choix d’outil…) dans les formats de Michael Nygard et MADR.

Voici quelques exemples représentatifs (tous disponibles dans ce dépôt d’exemples).

Plus d’exemples sont disponibles en anglais :

sur le dépôt de définition du format MADR,
sur le dépôt ADR tools dans le format de Michael Nygard.

On peut également trouver des exemples d’ADRs « en conditions réelles » dans certains projets open source, tels que le framework Arachne ou Tendermint.

Conclusion

Garder la documentation à jour n’est jamais quelque chose de trivial. En proposant une manière de documenter l’architecture dans la continuité, c’est à cette problématique que répondent les ADRs. Mais pour que cette réponse soit efficace, il est important de bien les utiliser. Pour y parvenir, si vous ne deviez retenir que trois choses de cet article :

Allons à l’essentiel : Que ce soit dans la sélection des décisions à documenter ou dans le contenu de chaque ADR, renoncez à l’exhaustivité pour vous concentrer sur ce qui est structurant.
Ne soyons pas dogmatiques : L’adoption doit se baser sur la compréhension des principes directeurs plutôt que sur un modèle particulier. Ici comme partout, l’amélioration continue doit s’appliquer.
La documentation ne remplace pas la communication : Validez les ADRs en tant qu’équipe pour faciliter l’appropriation des décisions, et ne vous servez pas de documents ou de process pour masquer les dysfonctionnements de l’équipe.