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 !

Transcript

1. Architecture Decision Records Arnaud Bos Toulouse DevFest 2018
3. Practical steps Theoretical knowledge Most useful when studying Most useful when working
4. Practical steps Theoretical knowledge Most useful when studying Most useful when working TUTORIAL LEARNING-ORIENTED
5. Practical steps Theoretical knowledge Most useful when studying Most useful when working HOW-TO PROBLEM-ORIENTED TUTORIAL LEARNING-ORIENTED
6. EXPLANATION UNDERSTANDING-ORIENTED HOW-TO PROBLEM-ORIENTED TUTORIAL LEARNING-ORIENTED Practical steps Theoretical knowledge Most useful when studying Most useful when working
7. REFERENCE INFORMATION-ORIENTED EXPLANATION UNDERSTANDING-ORIENTED HOW-TO PROBLEM-ORIENTED TUTORIAL LEARNING-ORIENTED Practical steps Theoretical knowledge Most useful when studying Most useful when working
8. Most useful when studying Theoretical knowledge Most useful when working
9. WHY Most useful when studying Theoretical knowledge Most useful when working
10. HOW WHY Most useful when studying Theoretical knowledge Most useful when working
11. Lightweight Architecture Decision Records HOW WHY Most useful when studying Theoretical knowledge Most useful when working
12. Context: Why
14. Context: why? • New features • Change existing features • Refactor
15. BREAKING CHANGE
16. BREAKING CHANGE STATUS QUO
18. Context: recap • Know thy history: keep track of events • Take better decisions with greater insight • Better ROI on documentation
19. Decision: What/How
20. Title ADR N°1: Use ADR Date Context Decision Status Consequences
21. Title ADR N°1: Use ADR Date (local-date) Context Decision Status Consequences
22. Title ADR N°1: Use ADR Date (local-date) Context Why? What’s the problem? Decision Status Consequences
23. Title ADR N°1: Use ADR Date (local-date) Context Why? What’s the problem? Decision How? We will ... Status Consequences
28. Title ADR N°1: Use ADR Date (local-date) Context Why? What’s the problem? Decision How? We will ... Status Proposed/Accepted/Superseded Consequences
29. Status: Proposed
30. Status: Accepted
31. Status: Superseded
32. Title ADR N°1: Use ADR Date (local-date) Context Why? What’s the problem? Decision How? We will ... Status Proposed/Accepted/Superseded Consequences + / -
33. Consequences: Good/Bad/Ugly
34. Consequences
35. • Rigor VS Flexibility: Find the right balance Consequences
36. • Rigor VS Flexibility: Find the right balance • Have someone who likes to write (a little), it helps Consequences
37. • Rigor VS Flexibility: Find the right balance • Have someone who likes to write, it helps • Be agile, do “design tasks” Consequences
38. • Rigor VS Flexibility: Find the right balance • Have someone who likes to write, it helps • Be agile, do “design tasks” • Hammock driven development Consequences
39. • 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
40. Status: Proposed Superseeds previous ADR N°0: “Outdated doc is better than no doc (lol)”
41. Arnaud Bos arnaud@monkeypatch.io
42. Divio: https://www.divio.com/blog/documentation/ Relevance: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions Moar: https://adr.github.io/ Even moar: https://github.com/joelparkerhenderson/architecture_decision_record/blob/01cc3c801b1c c61f82391a0a08986e4145e21c56/README.md Hammock-driven development https://www.youtube.com/watch?v=f84n5oFoZBc