Communicating and documenting architecture decisions

Transcript

1. Communicating and documenting architecture decisions
2. Why document architecture decisions?
3. Why did we decide to do it this way?
4. Problem: communicating decisions
5. • All developers in the organization
6. • All developers in the organization • Future self
7. • All developers in the organization • Future self • Future developers
8. • All developers in the organization • Future self • Future developers • Business
9. Recording decisions
10. ADRs (Architecture Decision Records) Michael Nygard
11. • documenting decisions in a lightweight way • doing it along with the code
12. • how to document • where to put the documentation
13. • how to document • where to put it
14. Right in the codebase!
15. • how to document • where to put it
16. • A text document (Markdown)
17. • A text document (Markdown) • One ADR per file
18. • A text document (Markdown) • One ADR per file • Short and straight to the point
19. 0001-scim-for-user-identity.md
20. /doc/adr/0001-scim-for-user-identity.md
29. github.com/npryce/adr-tools
30. Project-wide decisions
31. github.com/StudyTube/docs
32. Why ADR is a solution?
33. • increase in quality of pull requests
34. • increase in quality of pull requests • better engagement in all parts of the product
35. • increase in quality of pull requests • better engagement in all parts of the product • decrease in time spent explaining the solution
36. • increase in quality of pull requests • better engagement in all parts of the product • decrease in time spent explaining the solution • backup of your thought process
37. • increase in quality of pull requests • better engagement in all parts of the product • decrease in time spent explaining the solution • backup of your thought process • efficient onboarding
38. • increase in quality of pull requests • better engagement in all parts of the product • decrease in time spent explaining the solution • backup of your thought process • efficient onboarding • better communication with business
39. Architecture decision record
40. Next steps
41. • pull-request with first ADR
42. • pull-request with first ADR • update PR template
43. • pull request with first ADR • update PR template • request ADRs in pull request reviews
44. • pull request with first ADR • update PR template • request ADRs in pull request reviews • create /adr folder in doc repository
45. • The Github Blog: Why Write ADRs? - Eli Perkins • Cognitect: Documenting Architecture Decisions - Michael Nygard • Lead Dev New York: Communicating and documenting architectural decisions - David Ayers • TverIO: How to make a technical decision - Anton Davydov • pragmatic km guide - Register of architectural solutions