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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s