Architecture Decision Records: Being Agile with Architecture Decisions

Some architecture decisions are more consequential and higher impact than others, and need to be preserved. We work on systems where the architecture is too large for each person to hold all the details in their head. New team members struggle to understand what they need to know about the architecture. Current team members have challenges knowing what architecture decisions were made, by whom, and for what reason. Architecture Decision Records (ADRs) are a useful, agile, lightweight approach to tackling these, and other challenges.

This is the abstract from a workshop I ran at the OOP Conference for Software Architecture in February 2021. This is an updated version of workshops I have delivered on the same topic. The slides are available here.

Extended Abstract:
Are you working on a system where the architecture is too large for each person on the team to hold all the details in their head for all time? Do new team members struggle to understand what they need to know about the architecture? Do current team members have challenges in knowing what architecture decisions were made, by whom, and for what reason? Some architecture decisions are more consequential and higher impact than others, and need to be preserved.

The right level of architecture documentation supports agility. Architecture Decision Records (ADRs) are a useful, lightweight approach for this. Often no more than a page in length, they capture the key decisions that we need to remember. This hands-on session shares experiences with ADRs, giving you a set of tools to be successful in your team.

Through this interactive session we will explore these questions together:

  • What are Architecture Decision Records (ADRs) and why are they useful?
  • How do ADRs promote or help agility?
  • What are the motivations that led to trying ADRs for preserving decisions?
  • What are some scenarios and examples where ADRs are helpful?
  • What kinds of decisions should we record with ADRs, and why?
  • What are some of the cultural challenges associated with using ADRs, and how do we address them?

This session provides participants with hands-on practice of creating and reviewing ADRs. The session draws from experiences with multiple large-scale, global organisations and system architectures, and builds on established work with ADRs from other authors and practitioners.