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

Architecture Decision Records - Réconciliez-vous avec votre documentation !

Arnaud Bos
November 08, 2018

Architecture Decision Records - Réconciliez-vous avec votre documentation !

Given at Toulouse DevFest 2018
Video: http://bit.ly/adr-devfest-toulouse-2018-video
Abstract:
Les développeurs aiment écrire de la documentation… ou pas ! Pourtant même les plus réfractaires doivent l’admettre, garder une trace des décisions techniques prises au cours d’un projet peut s’avérer indispensable pour la pérennité et maintenabilité de celui-ci.

Alors comment éviter l’obsolescence programmée de la documentation, tout en réduisant la pénibilité de la rédaction ?

Depuis près d’un an, dans mon équipe, nous utilisons un format simple, les Architecture Decision Records (ADRs), pour écrire des documents d’architecture sous la forme d’un journal immuable. Cette technique simple gagne en popularité et a donné de bons résultats sur notre projet.

Durant cette présentation vous construirez en direct un ADR. En partant d’un problème constaté sur un projet, vous élaborerez une réponse technique qui servira de base à une implémentation ultérieure. Vous décrirez les raisons qui vous poussent à faire des compromis, tout en capturant le contexte dans lequel cette décision a été prise pour référence future.

Réconciliez vous avec votre documentation !

Arnaud Bos

November 08, 2018
Tweet

More Decks by Arnaud Bos

Other Decks in Technology

Transcript

  1. Practical steps Theoretical knowledge Most useful when studying Most useful

    when working HOW-TO PROBLEM-ORIENTED TUTORIAL LEARNING-ORIENTED
  2. Context: recap • Know thy history: keep track of events

    • Take better decisions with greater insight • Better ROI on documentation
  3. Title ADR N°1: Use ADR Date (local-date) Context Why? What’s

    the problem? Decision Status Consequences
  4. Title ADR N°1: Use ADR Date (local-date) Context Why? What’s

    the problem? Decision How? We will ... Status Consequences
  5. Title ADR N°1: Use ADR Date (local-date) Context Why? What’s

    the problem? Decision How? We will ... Status Proposed/Accepted/Superseded Consequences
  6. Title ADR N°1: Use ADR Date (local-date) Context Why? What’s

    the problem? Decision How? We will ... Status Proposed/Accepted/Superseded Consequences + / -
  7. • Rigor VS Flexibility: Find the right balance • Have

    someone who likes to write (a little), it helps Consequences
  8. • Rigor VS Flexibility: Find the right balance • Have

    someone who likes to write, it helps • Be agile, do “design tasks” Consequences
  9. • Rigor VS Flexibility: Find the right balance • Have

    someone who likes to write, it helps • Be agile, do “design tasks” • Hammock driven development Consequences
  10. • Rigor VS Flexibility: Find the right balance • Have

    someone who likes to write, it helps • Be agile, do “design tasks” • Hammock driven development • It’s not about tooling Consequences