Cet article fait suite à mon précédent article :
https://dev.to/onepoint/documentation-chaotique-diataxis-a-la-rescousse--3e9o

Quand on parle de ce dinosaure de DAT, il y a malgré tout un sujet à la mode : les Architecture Decision Records (ADR).

Créé par Michael Nygard en 2011, cette pratique gagne en popularité depuis quelques années. En 2024, nous pouvons en faire un passage obligé de la documentation technique d'architecture, surtout si on veut moderniser le DAT.

Dans cet article, je vous propose un tour d'horizon des ADR et de leurs bénéfices.

Sommaire :

• Définition d'une Architecture Decision Record
  • Structure d'une ADR
    • En-tête
    • Contexte
    • Solutions envisagées
    • Décision
    • Implications
  • Modèles disponibles
• Bénéfices des ADR
  • Transparence et traçabilité
  • Facilitation de la prise de décision
  • Amélioration de la maintenabilité
  • Intégration simplifiée des nouveaux collaborateurs
  • Prise de décision apaisée
• ADR : Le chaînon manquant
• Conclusion

Définition d'une Architecture Decision Record

Une ADR est à la fois une réunion et son compte-rendu portant sur une décision d'architecture.

Une ADR vise à réunir tous les sachants techniques concernés pour prendre une décision d'architecture collégiale sur une problématique et d'en identifier les implications.

Chaque participant peut exprimer librement sa vision et son point de vue.
La décision finale doit être collégiale et unanime.

Structure d'une ADR

En-tête

• Titre (de l'ADR)
• Date de la décision
• Statut (proposé, accepté, rejeté, remplacé, déprécié, etc.)
• Participants à la décision
• (Optionnel) Identifiant unique pour référence
• (Optionnel) Portée de l'ADR (solution, application, inter-applicatif, domaine, entreprise)

L'entête doit permettre d'identifier rapidement la portée, le statut, la date et les participants de l'ADR.

Contexte

• Situation actuelle
• Problématiques à résoudre
• (Optionnel) Contraintes (métier et techniques)
• (Optionnel) Exigences (normes, sécurité, métier, technique, standards)
• (Optionnel) Hypothèses

Le contexte doit exposer de manière simple la question/problématique à laquelle l'ADR doit apporter une réponse.
Dans l'idéal, on évitera de mêler plusieurs problématiques au sein d'une même ADR.

Solutions envisagées

• Description des scénarios possibles
• (Optionnel) Avantages et inconvénients de chaque scénario

Les solutions et scénarios techniques envisagés doivent être clairement détaillés avec leurs avantages et inconvénients (technique, coût, qualité, délai, ...)

Décision

• Choix du scénario retenu
• Justification du choix
• (Optionnel) Motifs de rejet des autres scénarios

La décision doit être justifiée. Idéalement, on indique ET les motifs du choix de scénario ET les motifs de rejets des autres scénarios

Implications

• Impacts identifiés
• Risques anticipés
• Références aux ADR connexes (notamment celles remplacées)
• (Optionnel) Références documentaires
  • (Optionnel) Cadrage projet (plan d'action, planning, ressources, charges)
  • (Optionnel) Critères de succès (métriques de suivi, indicateurs de performance)

La structure guide les échanges et sert de livrable final pour documenter la décision.

Une ADR possède un statut et suit un cycle de vie documentaire.
Elle reste valide tant que :

• La solution associée existe
• elle n'est pas remplacée par une nouvelle ADR

On fait donc référence dans les nouvelles ADR aux ADR qui sont remplacées

Modèles disponibles

J'ai adapté en français des templates anglais que j'appréciais :
ADR simple
ADR avancé
ADR exhaustif

C'est avant tout pour vous montrer des exemples de formes d'ADR.
Vous pouvez librement vous en inspirer selon vos besoins.

Bénéfices des ADR

Transparence et traçabilité

Les ADR, en tant que comptes-rendus, assurent :

• La transparence des décisions prises
• La traçabilité des choix effectués
• Un meilleur suivi de la dette technique associée

Fini les justifications du type "c'est historique" ou "les personnes concernées ont quitté l'entreprise"

Facilitation de la prise de décision

Les ADR :

• Structurent les discussions
• Permettent des décisions éclairées
• Documentent les implications des choix (dettes, contraintes)

La méthode demande d'examiner les différents choix et de justifier
pour le choix fait, quelles sont les raisons qui ont amené à ce choix
pour les autres, les raisons de leur non-sélection

Amélioration de la maintenabilité

Les ADR permettent :

• La conservation de l'historique décisionnel
• Une meilleure compréhension du système et de son évolution
• Une gestion facilitée de la dette technique

Cette approche implique une gestion documentaire qui permet de retrouver toutes les ADR et de les trier par ordre chronologique.

Intégration simplifiée des nouveaux collaborateurs

Les nouveaux membres comprennent mieux l'historique des choix architecturaux du système.

Cette approche vous retire la difficulté de répondre à la question "Mais pourquoi vous avez fait comme ça ?"

Prise de décision apaisée

Les décisions d'architecture, quand elles sont documentées, se dispersent généralement entre :

• Les comptes-rendus de comités (COPRO/COPIL/COSTRAT)
• Le DAT qui tente de couvrir tous les aspects (qui, quoi, comment, pourquoi)

Cette dispersion peut créer des situations complexes, comme l'illustre cette expérience personnelle :
J'accompagnais une équipe ayant choisi une migration Cloud type "lift and shift", sans services managés.
Quelques mois plus tard, l'apparition d'un nouveau service managé a créé des doutes dans l'équipe :

• Devons-nous changer notre approche ?
• Est-ce trop tard ?
• Pourquoi ne l'a-t-on pas anticipé ?
• Quel serait le coût d'un changement de direction alors qu'on approche de la fin ?

L'organisation d'une ADR nous a permis de :

• Réévaluer les différents scénarios possibles
• Intégrer les nouvelles informations sur le service managé
• Comparer objectivement les coûts et bénéfices de chaque option
• Documenter clairement le raisonnement derrière notre choix final

Ce cadre structuré a permis à l'équipe de prendre une décision éclairée, basée sur des critères objectifs plutôt que sur des impressions ou des craintes.
Faire cette ADR a transformé une situation stressante pour l'équipe en un processus de décision constructif et argumenté.

Voici l'exemple de cette ADR anonymisée :
ADR migration lift and shift

Prenons un autre exemple très parlant, une équipe face à un dilemme :
D'un côté, le standard de l'entreprise à respecter.

De l'autre, une date de mise en production incompatible avec la disponibilité de ce standard.

L'ADR a structuré la décision en deux temps :

1. Déployer d'abord une solution non-standard pour respecter les délais
2. Planifier ensuite une migration vers le standard

La dette technique a été précisée : un écart temporaire aux standards, clairement documenté et une remédiation planifiée.

ADR : Le chaînon manquant

Les ADR sont une réponse au besoin de documentation des décisions d'architecture. Leur adoption améliore la qualité et la pérennité des solutions techniques et de leurs dettes techniques.

Elles peuvent être un vrai levier de décision entre priorité métier et obsolescence technique.

Leur dimension temporelle nous permet aussi de :

• Mieux Comprendre le contexte de l'époque (comme "à ce moment-là, l'outil Z n'était pas encore assez développé")
• Evaluer si ces décisions sont toujours pertinentes aujourd'hui
• Éviter de juger les choix passés avec nos connaissances actuelles

Le plus gros bénéfice selon moi est de permettre d'avoir des discussions plus constructives et apaisées :
Au lieu de critiquer les anciens choix ou les priorités, on peut avoir des échanges plus sereins et objectifs, même sur des sujets difficiles.

La priorité peut être faite au métier en échange d'un engagement de remédiation de la dette technique.

Conclusion

En commençant à utiliser les ADR, j'ai compris que leur usage apportait un autre bénéfice pour le DAT.

En séparant la documentation des décisions, le DAT n'a plus à porter la charge de leur justification :

• Les décisions gagnent en visibilité.
• Le DAT perd du poids et gagne en lisibilité

Vous comprenez à présent pourquoi je voulais vous parler d'ADR dans le cadre de la modernisation du DAT.

Cet article fait partie du "Advent of Tech 2024 Onepoint", une série d'articles tech publiés par Onepoint pour patienter jusqu'à Noël.
Voir tous les articles du Advent of Tech 2024

Merci pour votre lecture.