WeAreDevelopers LIVE • Oct 12, 2020

Work efficiently with Architecture Decision Records (ADRs)

Johannes Dienst

Tired of continually re-debating identical architecture choices? Learn how adopting docs-as-code Architecture Decision Records turns undocumented history into searchable, traceable team wisdom.

Pause

Mute

Enter Fullscreen

#1 about 2 min

Introduction to documenting architecture decisions in agile teams

The challenges of decision-making and accountability in fast-paced product development environments.

#2 about 3 min

The consequences of undocumented and inherited technical decisions

A real-world example of maintaining legacy architecture and obscure integrations without historical context.

#3 about 3 min

Preventing repeated technical discussions by writing down decisions

How recurring architecture arguments drain team productivity and delay project milestones.

#4 about 3 min

Accountability and decision impact in a DevOps environment

Why teams operating their own software bear the immediate pain of bad architectural choices.

#5 about 4 min

Defining design decisions across code, solution, and application levels

The different tiers of technical choices and where architecture decision records appropriately apply.

#6 about 4 min

Using the arc42 template for lightweight architecture documentation

An overview of a structured framework for capturing system building blocks and runtime views.

#7 about 6 min

Implementing the Michael Nygard template for architecture decision records

A practical walkthrough of capturing status, context, and consequences using a deployed content management system example.

#8 about 2 min

Writing precise titles and active decisions for architectural searchability

Best practices for naming conventions and clearly stating chosen technical actions without ambiguity.

#9 about 2 min

Tracking the lifecycle of decisions with statuses and replacements

How to maintain a traceable history of superseded or revoked application models as infrastructure evolves.

#10 about 4 min

Capturing political and contextual constraints in architectural choices

Recording the specific project realities, tooling preferences, and hierarchal influences that shape a technical path.

#11 about 3 min

Documenting consequences and evaluating technical alternatives thoroughly

Why weighing the pros and cons of rejected options prevents future duplicated evaluation efforts.

#12 about 3 min

Crafting searchable titles for large architecture decision logs

Examples of specific, well-scoped record names that ensure team members can find historical context later.

#13 about 5 min

Transitioning from wikis to docs-as-code with AsciiDoc

Storing architectural records directly in version control alongside application code for better modularization tools.

#14 about 5 min

Generating static microsites for technical documentation using DocToolchain

Rendering easily browsable HTML interfaces from repository files to improve engineering and stakeholder visibility.

#15 about 3 min

Establishing peer review processes for architecture document merge requests

Requiring team consensus via pull requests to prevent the documentation tree from becoming an unstructured content dump.

#16 about 7 min

Scaling architecture transparency to reduce duplicate effort across organizations

Connecting decision repositories to corporate search engines to save distributed teams from resolving identical technical hurdles.

Matching moments

3:39 min

Balancing architectural tradeoffs and long-term decision tracking documentation

Luca Mezzalira

Luca Mezzalira · World Congress 2022

3:13 min

Using architecture decision records to formalize agent operating rules

Markus Eisele

Markus Eisele · World Congress 2026 Europe

2:04 min

Documenting architectural choices with a dedicated decision log

Szymon Chmal

Szymon Chmal · World Congress 2024

52 sec

Establishing ongoing documentation habits during software development

Luise Freese

Luise Freese · World Congress 2024

2:05 min

Documenting technical code and structural architectural decisions

Johan Hutting

Johan Hutting · World Congress 2024

2:23 min

Condensing the ARC 42 framework into one page

Benjamin Wolf

Benjamin Wolf +1 · World Congress 2025

More from WeAreDevelopers LIVE

WeAreDevelopers LIVE - Project Chopin: Make Your Team and Agents Play Along thumbnail

WeAreDevelopers LIVE - Project Chopin: Make Your Team and Agents Play Along

Chris Heilmann, Daniel Cranney, Krzysztof Cieślak

Fake or News - AI Toothbrushes, Carrier Pigeon Tech & Life on Mars - Krzysztof Cieślak thumbnail

Fake or News - AI Toothbrushes, Carrier Pigeon Tech & Life on Mars - Krzysztof Cieślak

Chris Heilmann, Daniel Cranney

Fake or News - AI Music Detectors, Translating Ancient Languages & Tiny Heads in Teslas - Eddie Jaoude thumbnail

Fake or News - AI Music Detectors, Translating Ancient Languages & Tiny Heads in Teslas - Eddie Jaoude

Chris Heilmann, Daniel Cranney

Fake or News: AI Agents Hire Each Other, Spider-Man Ads in Cars & RAM Thieves - Marc Plogas thumbnail

Fake or News: AI Agents Hire Each Other, Spider-Man Ads in Cars & RAM Thieves - Marc Plogas

Chris Heilmann, Daniel Cranney, Marc Plogas

WeAreDevelopers - Of Agents and Robots thumbnail

WeAreDevelopers - Of Agents and Robots

Chris Heilmann, Daniel Cranney, Marc Plogas

WeAreDevelopers LIVE - How DevRel Makes Tech More Human thumbnail

WeAreDevelopers LIVE - How DevRel Makes Tech More Human

Chris Heilmann, Daniel Cranney

Upcoming sessions on this topic

World Congress 2026 North America

September 24, 2026 · 10:20–10:50

Stage 4

AI Decision Observability: Enabling Transparency and Trust in Intelligent Systems

Amjad Shaikh, Soumil Mandal

Amjad Shaikh

Soumil Mandal

World Congress 2026 North America

September 24, 2026 · 11:10–11:15

Outdoor Stage

Architecting the 100X SDLC: Building Production Trust into AI-Assisted Delivery

Ranjan Parthasarathy

Founder, CPTO/CEO at AXIOMSTUDIO.AI

Ranjan Parthasarathy

World Congress 2026 North America

September 23, 2026 · 10:45–12:45

Stage 12

Architecting Multi-Agent Teams: Mastering the Orchestration Patterns of ADK 2

Christina Lin

Developer Relations Engineering Manager

Christina Lin

World Congress 2026 North America

September 24, 2026 · 16:10–16:40

Stage 3

Sandboxing the Swarm: Building Secure, Serverless AI Agents with Wasm

Lena Hall, Thorsten Hans

Lena Hall

Thorsten Hans

World Congress 2026 North America

September 24, 2026 · 14:10–14:40

Stage 4

Agentic Drift: keeping pace with your agents

John Coghlan

Senior Director, Developer Advocacy at GitLab

John Coghlan

World Congress 2026 North America

September 25, 2026 · 16:50–17:20

Outdoor Stage

Beyond the Code: Human-AI Synergies in Product Development

Ajita Kanchivakam Ananth

Staff Technical Program Manager at Google

Ajita Kanchivakam Ananth

Related videos

One Does Not Simply Make Architecture Decisions Alone thumbnail

Europe 2026 Virtual • 2 months ago

One Does Not Simply Make Architecture Decisions Alone

Vladas Diržys

Architecture Communication Canvas thumbnail

World Congress 2023 • almost 3 years ago

Architecture Communication Canvas

Gernot Starke, Benjamin Wolf

Documentation as a Tool: Introducing Documentation Driven Development thumbnail

World Congress 2024 • about 2 years ago

Documentation as a Tool: Introducing Documentation Driven Development

Abiodun Olowode

arc42 Meets AI: From Black Box to Blueprint thumbnail

Europe 2026 Virtual • 2 months ago

arc42 Meets AI: From Black Box to Blueprint

Nikita Golovko

42 x 2 Canvases Later: Two Years, Two Minds, Many Lessons thumbnail

World Congress 2025 • about 1 year ago

42 x 2 Canvases Later: Two Years, Two Minds, Many Lessons

Benjamin Wolf, Dr. Gernot Starke

Communicate efficiently with Software Architecture Diagrams thumbnail

World Congress 2022 • about 4 years ago

Communicate efficiently with Software Architecture Diagrams

Simon Lasselsberger

Related articles

DC

Daniel Cranney

The real reason we document our code

The world of software development moves fast. Technology is constantly changing, as are the tools we use with it, and even the role of a programmer is itself constantly in flux. However, some aspec...

almost 2 years ago

The real reason we document our code

BB

Benedikt Bischof

Humanizing Your Documentation

About the speaker:Carolyn Stransky is a journalist, software engineer, conference speaker and technical writer based in Berlin. This is how she describes herself on her website:Majority of the week...

almost 4 years ago

Humanizing Your Documentation

AA

Ali Alp

Why Event-Driven Architecture Isn’t About Speed (and When You Actually Need It)

Why Event-Driven Architecture Isn’t About Speed—And When You Actually Need It We’ve all seen it happen. An engineering team wants to feel like they belong in the “cool kids” club, so they grab Apac...

about 1 month ago

A developer workstation showing a code editor on one monitor, and a diagram on another

PK

Pawan Kumar Suresh

Velocity with Guardrails: How Technical Teams Can Move Fast Without Losing Decision Integrity

“Move fast” is easy advice to give, but often very difficult to actually act on. When technical teams move slowly - or slower than they would like to - it is not because the people within the team ...

about 1 month ago

A dual monitor set up showing code on screen, and a series of documents on the other, with the titles: decisions, risks, ownership and assumptions

From learning to earning

Jobs that call for the skills explored in this talk.

IT-Architekt Cloud-native Plattformen & Frameworks

Aok Systems Gmbh

München, Germany

Rancher Grafana Ansible

18 days ago • Verified

Sr. Solution Architect

Detroit, United States

Expert Remote DevOps Terraform Kubernetes

Principal Solutions Architect, Professional Services

Barcelona, Spain

€119k–170k Okta Docker OpenID

20 days ago • Verified

Founding Developer Advocate

San Francisco, United States

Experienced $150k–190k Remote GIT Bash Linux

Data Architect-Manager

JSON Workday Mulesoft

Principal Solutions Architect, Professional Services

€119k–170k Okta Docker OpenID