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 · 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 - Is CSS Catching Up to Flash? thumbnail
1:03:33
10 days ago

WeAreDevelopers LIVE - Is CSS Catching Up to Flash?

Chris Heilmann, Daniel Cranney, Bramus Van Damme

WeAreDevelopers LIVE - Project Chopin: Make Your Team and Agents Play Along thumbnail
1:21:17
17 days ago

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 Cieślak thumbnail
4:23
18 days ago

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

Chris Heilmann, Daniel Cranney

WeAreDevelopers LIVE - Open Source Agent Toolkits thumbnail
1:00:38
24 days ago

WeAreDevelopers LIVE - Open Source Agent Toolkits

Chris Heilmann, Daniel Cranney, Eddie Jaoude

Fake or News - AI Music Detectors, Translating Ancient Languages & Tiny Heads in Teslas - Eddie Jaoude thumbnail
6:16
25 days ago

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
5:46
30 days ago

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

Chris Heilmann, Daniel Cranney, Marc Plogas

Related videos

One Does Not Simply Make Architecture Decisions Alone thumbnail
36:15
Europe 2026 Virtual • 2 months ago

One Does Not Simply Make Architecture Decisions Alone

Vladas Diržys

Architecture Communication Canvas thumbnail
26:15
World Congress 2023 • about 3 years ago

Architecture Communication Canvas

Gernot Starke, Benjamin Wolf

Documentation as a Tool: Introducing Documentation Driven Development thumbnail
22:45
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
25:53
Europe 2026 Virtual • 3 months ago

arc42 Meets AI: From Black Box to Blueprint

Nikita Golovko

42 x 2 Canvases Later: Two Years, Two Minds, Many Lessons thumbnail
27:56
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
28:11
World Congress 2022 • over 4 years ago

Communicate efficiently with Software Architecture Diagrams

Simon Lasselsberger

Related articles

From learning to earning

Jobs that call for the skills explored in this talk.