Architecture decision records - How not to get lost in the past

ADR, or Architecture Decision Record, is a valuable tool in software development for several reasons. It provides a centralized location for documenting and tracking architectural decisions, aiding both current and future team members. ADRs enhance communication among team members by documenting the rationale behind architectural decisions, especially beneficial during onboarding of new team members or when revisiting decisions. They serve as a knowledge base, enabling teams to learn from past decisions and refine their decision-making process. Additionally, ADRs contribute to transparency by helping stakeholders understand the reasons behind specific architectural choices. As with any other tool or process, introducing them into an organization can face several obstacles, and overcoming these challenges is crucial for successful implementation. In this talk I go through some common problems and our way of solving them.

1. # Architecture decision records ## How not to get lost in the past

2. # What is this presentation about? What is an ADR? How does it look like in practice? Obstacles during the introduction How do we overcome them? 6% 2:32

3. # And what it isn’t? Why ADRs are good? ADR good practices ADR anti-patterns Single process to use 6% 2:32

4. # About me Krisztián Papp Principal Software Engineer @ Diligent <3 Neovim Enemy of the mutable state Founder/co-host @ letscode.hu medium.com/@tacsiazuma twitter.com/Tacsiazuma 9% 3:32

5. Who used ADRs in the workplace? Who attempted to introduce it? Who failed miserably? 12% 4:32

6. > An architecture decision is a justified software design choice that addresses a functional or non-functional requirement that is architecturally significant. https://adr.github.io/ 15% 5:32

7. # Some example ADs Using event-driven architecture Choosing a cloud provider Decomposing to microservices Replacing MariaDB with <add your favorite NoSQL database here> Merging to a monorepo Using peer -to-peer instead of client-server Creating a data lake 18% 6:32

8. # Title: "Redis as a persistent storage" ## Context: "We need a big key-value store and apparently DynamoDB has a 400 KByte size limit while Redis has 512 MByte . Also its blazingly fast." ## Decision: "We will use a Redis cluster to store everything." ## Status: "decided" ## Consequences: ### Good: "We don't need a caching layer anymore." ### Bad: "We have to provision a huge Redis cluster to fit everything in memory but thats on operations team and they like challenges anyways." 21% 7:32

9. # How does it look like in practice? 24% 8:32

10. 27% 9:32

11. 30% 10:32 # Log4brains markdown based renders HTML seamless Github integration

12. 33% 11:32

13. 36% 12:32 Idea Check for existing ADR Open a PR with proposed state Formal checks on PR ADR review Finalizing decision # Summary

14. 39% 13:32

15. # Obstacles Overloaded teams ADR as a bottleneck People who hate writing documentation People who love writing documentation You need sponsors Organization structure You need followers No silver bullet 42% 14:32

16. # Overloaded teams Writing ADRs feel like a burden Reviewing it also feels like one Apathy Teams demanding architects to do the job 45% 15:32

17. # McDonalds to the rescue > It’s as if we’ve broken the ice with the worst possible idea, and now that the discussion has started, people suddenly get very creative. I call it the McDonald’s Theory: people are inspired to come up with good ideas to ward off bad ones. https://jonbell.medium.com/mcdonalds-theory-9216e1c9da7d 48% 16:32

18. # Kafka to the rescue Hey, you should figure out which database to use in our Content Service. Let’s use Kafka! You must be joking, right? If you have a better idea, then why don’t you come up with an ADR? 51% 17:32

19. 33% 11:32

20. # ADR as a bottleneck Nitty gritty details as ADRs Missing out some important decisions Decisions must be made A.S.A.P Unreviewed ADRs rotting in the repo Involving external parties 45% 15:32

21. 33% 11:32

22. # ADR as a bottleneck Example good/bad ADRs Retrospective ADRs Dedicated reviewers on rotation Fast track ADRs on-demand ADRs should be actionable Stakeholder involvement planned ahead 45% 15:32

23. # People who hate writing documentation Impostor syndrome “Mom, can we not do it?” Documentation have to be maintained They created wiki pages which has been left to rot 54% 18:32

24. 33% 11:32

25. # Babysteps Review their ADRs privately first / get others to review it ADRs are immutable - no need to maintain it ADRs are short, no need to spend hours writing it It is a way to grow 57% 19:32

26. # People who love writing documentation ADR that smells like a confluence page They are usually good at English Presenting their ADR on a review session takes up the whole meeting Duplicating wiki pages as ADRs - sometimes even linking the two together 60% 20:32

27. 33% 11:32

28. # Contain/direct their creativity ADRs should be short but can contain links Timebox the ADR reviews - keep it short Have an example ADR as a baseline for length Let them catch/fix typos, grammar errors in other ADRs. 63% 21:32

29. 33% 11:32

30. # You need sponsors It can lose traction easily You need buy-in Who should be involved in the process? Convince them… … or what about KPIs? 66% 22:32

31. # Start small Shadow ADRs in a single team Find pain points across the organization Get the least amount of people involved Showcase it after it is adopted Management approval No guinea pig feeling 69% 23:32

32. # Go big Announce important decisions via ADRs It can be a forum to get people’s ideas out there Involve the decisions on painful areas to attract more attention Extend it to other teams 72% 24:32

33. # Organization structure Different products/teams Wide variety of tech stack Autonomous teams What are the benefits? Us <-> them Knowledge silos 45% 15:32

34. 45% 15:32

35. 45% 15:32

36. # Organization structure Common problems Different stack != special Continuous learning (trade-offs, patterns) Lot of information Promote exciting topics 45% 15:32

37. 45% 15:32

38. # You need followers You create ADRs You review ADRs You facilitate the review sessions … and you go on vacation/leave/get sick/get fired 75% 25:32

39. # You need followers 75% 25:32

40. # The right people Host a meetup/brown bag to spread the word Find the ones interested Early adopters Self-organizing group Spread the knowledge 78% 26:32

41. # There is no silver bullet The process should be tailored to the organization Management challenge Fun > doing it perfect Iterate on the process Merge earlier initiatives ADRs != fancy UI 81% 27:32

42. # Further reading https://adr.github.io/ https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html https://ozimmer.ch/practices/2023/04/03/ADRCreation.html https://github.com/thomvaill/log4brains 84% 28:32

43. # Q&A 81% 27:32

44. # Thank you for your attention! 90% 30:32