Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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.

Sébastien LECACHEUR

June 29, 2023
Tweet

More Decks by Sébastien LECACHEUR

Other Decks in Programming

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

    View Slide

  2. @slecache #BreizhCamp #architecture #ADR
    Les douleurs

    View Slide

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

    View Slide

  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 ? »

    View Slide

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

    View Slide

  6. @slecache #BreizhCamp #architecture #ADR
    L’architecture agile émergente

    View Slide

  7. @slecache #BreizhCamp #architecture #ADR
    Solution

    View Slide

  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

    View Slide

  9. @slecache #BreizhCamp #architecture #ADR
    Keep It Simple, Stupid!

    View Slide

  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

    View Slide

  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

    View Slide

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

    View Slide

  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

    View Slide

  14. @slecache #BreizhCamp #architecture #ADR
    Exemple d’ADR

    View Slide

  15. @slecache #BreizhCamp #architecture #ADR
    Exemple de decision log

    View Slide

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

    View Slide

  17. @slecache #BreizhCamp #architecture #ADR
    Cycle de vie d’un ADR
    Immuable !!

    View Slide

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

    View Slide

  19. @slecache #BreizhCamp #architecture #ADR
    Take away

    View Slide

  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

    View Slide

  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)

    View Slide

  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à. »

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  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…

    View Slide

  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….

    View Slide

  30. @slecache #BreizhCamp #architecture #ADR
    Merci

    View Slide

  31. @slecache #BreizhCamp #architecture #ADR
    Questions & réponses

    View Slide

  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/

    View Slide