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.

Target Audience: Anyone who affects, or is affected by architecture decisions
Prerequisites: Some experience in software design and architecture would be beneficial
Level: Advanced

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.