WeAreDevelopers Logo WeAreDevelopers
Sign in
For You LIVE
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 Β· WWC 2022

3:13 min

Using architecture decision records to formalize agent operating rules

Markus Eisele Markus Eisele Β· WWC Europe 2026

2:04 min

Documenting architectural choices with a dedicated decision log

Szymon Chmal Szymon Chmal Β· WWC 2024

52 sec

Establishing ongoing documentation habits during software development

Luise Freese Luise Freese Β· WWC 2024

2:05 min

Documenting technical code and structural architectural decisions

Johan Hutting Johan Hutting Β· WWC 2024

2:23 min

Condensing the ARC 42 framework into one page

Benjamin Wolf Benjamin Wolf +1 Β· WWC 2025

More from WeAreDevelopers LIVE

Aliens in Quarantine, Python Deprecates Loops, and AI Buys Old Books - Zbyszek Tenerowicz thumbnail
5:43
5 days ago

Aliens in Quarantine, Python Deprecates Loops, and AI Buys Old Books - Zbyszek Tenerowicz

Chris Heilmann, Daniel Cranney

WeAreDevelopers LIVE - Node and Package Security thumbnail
1:08:30
5 days ago

WeAreDevelopers LIVE - Node and Package Security

Chris Heilmann, Daniel Cranney, Zbyszek Tenerowicz

WeAreDevelopers LIVE - Streaming HTML thumbnail
1:10:26
12 days ago

WeAreDevelopers LIVE - Streaming HTML

Chris Heilmann, Daniel Cranney, Jad Joubran

WeAreDevelopers LIVE - CODE100 at WeAreDevelopers Europe thumbnail
1:02:34
19 days ago

WeAreDevelopers LIVE - CODE100 at WeAreDevelopers Europe

Chris Heilmann, Daniel Cranney, Justin Halsall, Werner Jeschko, Nicole Jeschko, Mirco Tomić

WeAreDevelopers LIVE - Web Performance in an AI World thumbnail
1:07:59
26 days ago

WeAreDevelopers LIVE - Web Performance in an AI World

Chris Heilmann, Daniel Cranney

FIFA Hack, Midjourney Does Ultrasounds, and Trampoline Traffic Lights - Nicole Jeschko and Werner Jeschko thumbnail
5:55
about 2 months ago

FIFA Hack, Midjourney Does Ultrasounds, and Trampoline Traffic Lights - Nicole Jeschko and Werner Jeschko

Chris Heilmann, Daniel Cranney

Upcoming sessions on this topic

Open session

World Congress 2026 North America

AI Decision Observability: Enabling Transparency and Trust in Intelligent Systems

Amjad Shaikh, Soumil Mandal

Amjad Shaikh
Soumil Mandal
Open session

World Congress 2026 North America

Agentic Drift: keeping pace with your agents

John Coghlan

Senior Director, Developer Advocacy at GitLab

John Coghlan
Open session

World Congress 2026 North America

AI-Driven API Design

Mike Amundsen

Author, Adviser, Trainer

Mike Amundsen
Open session

World Congress 2026 North America

Beyond the Code: Human-AI Synergies in Product Development

Ajita Kanchivakam Ananth

Staff Technical Program Manager at Google

Ajita Kanchivakam Ananth
Open session

World Congress 2026 North America

Designing APIs That Survive AI Agents at Scale

Phani Pendurthi

Mastercard, Principal Software Engineer

Phani Pendurthi
Open session

World Congress 2026 North America

AI ROI: The Hard Unit Economics of AI-Native Engineering

Manu Gurudatha

Manu Gurudatha, VP of Engineering at PagerDuty

Manu Gurudatha

Related videos

One Does Not Simply Make Architecture Decisions Alone thumbnail
36:15
Europe 2026 Virtual β€’ 28 days ago

One Does Not Simply Make Architecture Decisions Alone

Vladas DirΕΎys

Architecture Communication Canvas thumbnail
26:15
WWC 2023 β€’ almost 3 years ago

Architecture Communication Canvas

Gernot Starke, Benjamin Wolf

Documentation as a Tool: Introducing Documentation Driven Development thumbnail
22:45
WWC 2024 β€’ almost 2 years ago

Documentation as a Tool: Introducing Documentation Driven Development

Abiodun Olowode

42 x 2 Canvases Later: Two Years, Two Minds, Many Lessons thumbnail
27:56
WWC 2025 β€’ 12 months ago

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

Benjamin Wolf, Dr. Gernot Starke

Communicate efficiently with Software Architecture Diagrams thumbnail
28:11
WWC 2022 β€’ about 4 years ago

Communicate efficiently with Software Architecture Diagrams

Simon Lasselsberger

Enhancing Developer Experience During Architecture Modernization thumbnail
26:53
almost 2 years ago

Enhancing Developer Experience During Architecture Modernization

Mauricio Frias

Related articles

From learning to earning

Jobs that call for the skills explored in this talk.