Construire un registre de choix d'architecture avec les ADR - Codeurs en Seine 2024 - Conférence

Slide 1

Slide 1 text

@slecache #Codeurs2024 #architecture #ADR Construire un registre de choix d’architecture avec les ADR Architecture Decision Records Sébastien Lecacheur 🏢 Odigo 📅 21/11/24 ⌚ 16h30 📍 Codeurs En Seine 🚪 Salle C

Slide 2

Slide 2 text

@slecache #Codeurs2024 #architecture #ADR Les douleurs

Slide 3

Slide 3 text

@slecache #Codeurs2024 #architecture #ADR Le nouvel arrivant « Mais pourquoi fait-on ça ? » « Et pourquoi ceci ? » « Pourquoi cela ? » « Avez-vous pensé à ça ? » …

Slide 4

Slide 4 text

@slecache #Codeurs2024 #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 ? » …

Slide 5

Slide 5 text

@slecache #Codeurs2024 #architecture #ADR Le porté disparu « On a toujours fait comme ça ! » « Je ne sais pas… C’est historique. » …

Slide 6

Slide 6 text

@slecache #Codeurs2024 #architecture #ADR L’architecture agile émergente

Slide 7

Slide 7 text

@slecache #Codeurs2024 #architecture #ADR Solution

Slide 8

Slide 8 text

@slecache #Codeurs2024 #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

Slide 9

Slide 9 text

@slecache #Codeurs2024 #architecture #ADR Keep It Simple, Stupid!

Slide 10

Slide 10 text

@slecache #Codeurs2024 #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

Slide 11

Slide 11 text

@slecache #Codeurs2024 #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

Slide 12

Slide 12 text

@slecache #Codeurs2024 #architecture #ADR Modèle minimaliste ● Titre ● Date ● Statut ● Contexte ○ problème ○ contraintes ○ hypothèses ● Décision ● Conséquences

Slide 13

Slide 13 text

@slecache #Codeurs2024 #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

Slide 14

Slide 14 text

@slecache #Codeurs2024 #architecture #ADR Exemple d’ADR

Slide 15

Slide 15 text

@slecache #Codeurs2024 #architecture #ADR Exemple de decision log

Slide 16

Slide 16 text

@slecache #Codeurs2024 #architecture #ADR Processus de prise de décision 1. Identification ☝ 2. Brainstorming 🧠 3. Options 📋 4. Consensus 🌀 5. Décision 🎯

Slide 17

Slide 17 text

@slecache #Codeurs2024 #architecture #ADR Cycle de vie d’un ADR Immuable !!

Slide 18

Slide 18 text

@slecache #Codeurs2024 #architecture #ADR Les outils ● Markdown ○ Github/Gitlab ○ outils ● Texte ● Wiki ● Confluence ● Notion ● … ¯\_(ツ)_/¯

Slide 19

Slide 19 text

@slecache #Codeurs2024 #architecture #ADR Take away

Slide 20

Slide 20 text

@slecache #Codeurs2024 #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

Slide 21

Slide 21 text

@slecache #Codeurs2024 #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)

Slide 22

Slide 22 text

@slecache #Codeurs2024 #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à. »

Slide 23

Slide 23 text

@slecache #Codeurs2024 #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

Slide 24

Slide 24 text

Slide 25

Slide 25 text

Slide 26

Slide 26 text

Slide 27

Slide 27 text

@slecache #Codeurs2024 #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 ● Renommer le titre de l’ADR après acceptation

Slide 28

Slide 28 text

@slecache #Codeurs2024 #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…

Slide 29

Slide 29 text

@slecache #Codeurs2024 #architecture #ADR Ce qu’il faut retenir Le « Pourquoi ? » Pragmatique Collaboratif A vous de jouer et d’alimenter votre registre de décisions….

Slide 30

Slide 30 text

@slecache #Codeurs2024 #architecture #ADR Merci

Slide 31

Slide 31 text

@slecache #Codeurs2024 #architecture #ADR Questions & réponses

Slide 32

Slide 32 text

@slecache #Codeurs2024 #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/