Construire un registre de choix d'architecture avec les ADR - BreizhCamp 2023 - Tools-in-Action

Pourquoi et comment tracer vos choix d'architecture ?

Venez découvrir une méthode pour tracer vos choix d'architecture de plus en plus populaire, qui nous fait gagner énormément de temps et qui augmente la connaissance des équipes. Cette méthode, utilisant les ADR (Architecture Decision Record), met en avant la simplicité : Keep It Simple, Stupid !

Au travers d'un retour d'expérience de plusieurs années, nous verrons donc comment documenter le plus simplement possible un choix d'architecture ou de conception tout en gardant une trace du contexte, des options et des compromis qui ont menés à cette décision.

Cette session sera également l'occasion de revenir sur la mise en pratique à l'échelle de l'entreprise.

Transcript

1. @slecache #BreizhCamp #architecture #ADR Construire un registre de choix d’architecture avec les ADR Architecture Decision Records Sébastien Lecacheur 🏢 Odigo 📅 29/06/23 ⌚ 17h 📍 BreizhCamp 🚪 Amphi A
2. @slecache #BreizhCamp #architecture #ADR Les douleurs
3. @slecache #BreizhCamp #architecture #ADR Le nouvel arrivant « Mais pourquoi fait-on ça ? » « Et pourquoi ceci ? » « Pourquoi cela ? » « Avez-vous pensé à ça ? » …
4. @slecache #BreizhCamp #architecture #ADR Le troll radoteur « Mais pourquoi utilisez-vous cette techno obsolète ? » « Mais pourquoi avez-vous fait comme ça ? » « Mais pourquoi utilisez-vous cette techno obsolète ? » « Mais pourquoi avez-vous fait comme ça ? » « Mais pourquoi utilisez-vous cette techno obsolète ? » …
5. @slecache #BreizhCamp #architecture #ADR Le porté disparu « On a toujours fait comme ça ! » « Je ne sais pas… C’est historique. » …
6. @slecache #BreizhCamp #architecture #ADR L’architecture agile émergente
7. @slecache #BreizhCamp #architecture #ADR Solution
8. @slecache #BreizhCamp #architecture #ADR Qu’est-ce qu’un choix d’architecture ? • Un problème de conception ou technique à résoudre • dans un contexte ◦ temporalité ◦ contraintes ◦ exigences ◦ hypothèses • avec plusieurs options
9. @slecache #BreizhCamp #architecture #ADR Keep It Simple, Stupid!
10. @slecache #BreizhCamp #architecture #ADR Lightweight Architecture Decision Records (ADR) • Capture d'une seule décision de conception ou technique • Stockée dans un fichier Markdown au format simple • Léger et facile à utiliser
11. @slecache #BreizhCamp #architecture #ADR Les objectifs • Éviter l'acceptation aveugle et l'inversion aveugle lorsque vous êtes confronté à des décisions passées • Accélérer l'intégration des nouveaux développeurs dans un projet • Formaliser un processus de prise de décision collaboratif
12. @slecache #BreizhCamp #architecture #ADR Modèle minimaliste • Titre • Date • Statut • Contexte ◦ problème ◦ contraintes ◦ hypothèses • Décision • Conséquences
13. @slecache #BreizhCamp #architecture #ADR Modèle utilisé • Titre • Date • Statut • Contexte ◦ problème ◦ contraintes ◦ hypothèses • Décision • Conséquences • Porteur • Parties prenantes • Facteurs de décision • Décision ◦ justification • Conséquences ◦ positives ◦ négatives • Options ◦ pros ◦ cons
14. @slecache #BreizhCamp #architecture #ADR Exemple d’ADR
15. @slecache #BreizhCamp #architecture #ADR Exemple de decision log
16. @slecache #BreizhCamp #architecture #ADR Processus de prise de décision 1. Identification ☝ 2. Brainstorming 🧠 3. Options 📋 4. Consensus 🌀 5. Décision 🎯
17. @slecache #BreizhCamp #architecture #ADR Cycle de vie d’un ADR Immuable !!
18. @slecache #BreizhCamp #architecture #ADR Les outils • Markdown ◦ Github/Gitlab ◦ outils • Texte • Wiki • Confluence • Notion • … ¯\_(ツ)_/¯
19. @slecache #BreizhCamp #architecture #ADR Take away
20. @slecache #BreizhCamp #architecture #ADR Les bénéfices • Source de vérité unique • Partage de connaissance (et retour d’expérience) • Transparence • Montée en compétence sur les choix d’architecture • Tout le monde peut prendre un sujet (modèle participatif) • Adhésion aux choix • Historique des prises de décision • Communication asynchrone (avec les commentaires) • Rappel avec un simple lien (gain de temps) -> Don’t Repeat Yourself
21. @slecache #BreizhCamp #architecture #ADR Les difficultés • Trouver un porteur • Suivi des ADR • Accessibilité/recherche des ADR • Structure mais ne donne pas la solution (à la prise de décision)
22. @slecache #BreizhCamp #architecture #ADR Les victoires • La première fois qu’une personne demande « Il ne faudrait pas écrire un ADR là ? » • « Mais on n’a jamais dit que l’on allait faire ça. » • « Mais pourquoi vous êtes partis sur cette solution ? » • A chaque fois qu’une personne dit « Il faut écrire un ADR là. »
23. @slecache #BreizhCamp #architecture #ADR Retour d’expérience Etape Détail Cible 👍 👎 1. MADR (Markdown ADR) dans Git • Merge request • Discussion • Outillage: adr-tools 1 équipe de dév co-localisé avec le code difficilement accessible aux non-dév 2. Decision log dans Confluence • Commentaires équipes produits accessible à tous suivi difficile 3. Tickets de décision dans Jira entreprise suivi et cycle de vie pas conçu pour de la documentation 4. Tickets + decision log synchro entre ticket & decision log
24. @slecache #BreizhCamp #architecture #ADR Retour d’expérience Etape Détail Cible 👍 👎 1. MADR (Markdown ADR) dans Git • Merge request • Discussion • Outillage: adr-tools 1 équipe de dév co-localisé avec le code difficilement accessible aux non-dév 2. Decision log dans Confluence • Commentaires équipes produits accessible à tous suivi difficile 3. Tickets de décision dans Jira entreprise suivi et cycle de vie pas conçu pour de la documentation 4. Tickets + decision log synchro entre ticket & decision log
25. @slecache #BreizhCamp #architecture #ADR Retour d’expérience Etape Détail Cible 👍 👎 1. MADR (Markdown ADR) dans Git • Merge request • Discussion • Outillage: adr-tools 1 équipe de dév co-localisé avec le code difficilement accessible aux non-dév 2. Decision log dans Confluence • Commentaires équipes produits accessible à tous suivi difficile 3. Tickets de décision dans Jira entreprise suivi et cycle de vie pas conçu pour de la documentation 4. Tickets + decision log synchro entre ticket & decision log
26. @slecache #BreizhCamp #architecture #ADR Retour d’expérience Etape Détail Cible 👍 👎 1. MADR (Markdown ADR) dans Git • Merge request • Discussion • Outillage: adr-tools 1 équipe de dév co-localisé avec le code difficilement accessible aux non-dév 2. Decision log dans Confluence • Commentaires équipes produits accessible à tous suivi difficile 3. Tickets de décision dans Jira entreprise suivi et cycle de vie pas conçu pour de la documentation 4. Tickets + decision log synchro entre ticket & decision log
27. @slecache #BreizhCamp #architecture #ADR Astuces • Numéroter les ADR • Versionner les ADR • Créer automatiquement l’index des MADR • Encourager l’échange • Documenter seulement le « Pourquoi ? » • Tout expliciter • Rester concis (pas plus de 1 ou 2 pages) • Proposer une option naïve/bête si pas d’option/alternative • Découper l’ADR si trop d’options • Ajouter un schéma si besoin • Trouver le consensus avant de soumettre l’ADR • Ne pas modifier un ADR accepted ou rejected
28. @slecache #BreizhCamp #architecture #ADR Aller plus loin • Documentations ◦ https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions ◦ https://adr.github.io/ ◦ https://github.com/joelparkerhenderson/architecture-decision-record • Formats: ADR, MADR, Y-Statement… • Outillage ◦ ADR Manager (Github viewer) ◦ ADR Manager (VSCode extension) ◦ Log4brains (WebApp + CLI) ◦ adr-tools, adrgen (CLI) • Alternatives : Architecture Haiku • Decision making, scoring grid, etc…
29. @slecache #BreizhCamp #architecture #ADR Ce qu’il faut retenir Le « Pourquoi ? » Pragmatique Collaboratif A vous de jouer et d’alimenter votre registre de décisions….
30. @slecache #BreizhCamp #architecture #ADR Merci
31. @slecache #BreizhCamp #architecture #ADR Questions & réponses
32. @slecache #BreizhCamp #architecture #ADR Ressources • Google font : Architects Daughter • Flaticons: black hand drawn • https://www.archdaily.com/183687/missing-architecture-have-you-seen-me • https://www.commitstrip.com/fr/2016/02/15/our-companys-greatest-project/ • https://pixabay.com/illustrations/blueprint-technical-drawing-4056027/