Johannes Dienst

Work efficiently with Architecture Decision Records (ADRs)

A simple text file saved hundreds of teams from solving the same problem twice. Learn how Architecture Decision Records can scale your organization's technical knowledge.

Work efficiently with Architecture Decision Records (ADRs)
#1about 7 minutes

Why documenting architectural decisions is crucial

Undocumented decisions lead to repeated discussions and confusion, wasting valuable team time and effort.

#2about 6 minutes

Defining design decisions at different levels of abstraction

Design decisions exist at the code, solution, and application levels, with architectural decisions focusing on high-impact choices like patterns and frameworks.

#3about 3 minutes

Using the arc42 template for lightweight documentation

The arc42 template provides a standardized, lightweight structure for technical documentation, with a dedicated chapter for architecture decisions.

#4about 6 minutes

Understanding the structure of an Architecture Decision Record

An ADR template captures the title, decision, status, context, consequences, and alternatives to provide a clear and concise record of a choice.

#5about 9 minutes

Best practices for writing effective ADR components

Writing effective ADRs requires precise language, clear status tracking, comprehensive context, and a thorough evaluation of alternatives.

#6about 10 minutes

Managing many ADRs using a Docs as Code approach

A Docs as Code workflow using AsciiDoc and Git enables versioning, peer review, and the generation of a searchable static site for large ADR collections.

#7about 6 minutes

Scaling ADRs for team alignment and corporate efficiency

Implementing a peer review process for documentation improves quality, while making ADRs transparent across an organization prevents redundant work and saves significant costs.

#8about 3 minutes

Making ADRs discoverable with an internal search engine

Integrating the ADR microsite with a corporate search engine makes architectural decisions easily discoverable, fostering knowledge sharing across the entire organization.

Related jobs
Jobs that call for the skills explored in this talk.

Matching moments

Making explicit and collaborative architectural decisions
01:36 MIN

Making explicit and collaborative architectural decisions

Remote Mob Programming - At home, but not alone

Viewing software architecture as a series of trade-offs
03:32 MIN

Viewing software architecture as a series of trade-offs

Micro-frontends anti-patterns

Creating effective documentation for future contributors
02:06 MIN

Creating effective documentation for future contributors

Open sourcing a library: how hard can that be?

Documenting choices with an architecture decision log
03:27 MIN

Documenting choices with an architecture decision log

Resistant to hype: How to avoid being deceived by technological trends?

A pragmatic approach to tool selection and evolution
01:21 MIN

A pragmatic approach to tool selection and evolution

From Factory Floor to Kubernetes Core: Building an Edge Platform One Step at a Time

Building a tech strategy focused on developer enablement
03:51 MIN

Building a tech strategy focused on developer enablement

Enhancing Developer Experience During Architecture Modernization

Recognizing the root causes of technical debt
03:45 MIN

Recognizing the root causes of technical debt

We (don't) need a software architect!?!

Common challenges in architecture documentation
01:52 MIN

Common challenges in architecture documentation

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

Featured Partners

Related Videos

See all videos
"I will remember that" and other lies - Why documentation matters and it makes your apps better
25:25

"I will remember that" and other lies - Why documentation matters and it makes your apps better

Luise Freese

Technical Documentation - How Can I Write Them Better and Why Should I Care?
31:23

Technical Documentation - How Can I Write Them Better and Why Should I Care?

Hila Fish

Architecture Communication Canvas
26:15

Architecture Communication Canvas

Gernot Starke & Benjamin Wolf

We (don't) need a software architect!?!
24:52

We (don't) need a software architect!?!

Hendrik Lösch

Documentation as a Tool: Introducing Documentation Driven Development
22:45

Documentation as a Tool: Introducing Documentation Driven Development

Abiodun Olowode

Resolving technical debts in software architecture
24:38

Resolving technical debts in software architecture

Carola Lilienthal

The Lifehacker's Guide to Software Architecture
25:40

The Lifehacker's Guide to Software Architecture

Julian Lang

It’s all about the domain, honey ! Experiences from 15 years of Domain-Driven Design
43:13

It’s all about the domain, honey ! Experiences from 15 years of Domain-Driven Design

Carola Lilienthal

Related Articles

View all articles
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 aspects of software engineering are so foundational that w...
The real reason we document our code
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, I'm a frontend engineer focused on accessibility, d...
Humanizing Your Documentation
Chris Heilmann
Dev Digest 131 - AI'm not sure about OSS
News and ArticlesRust and Typescript are rising stars in programming languages 2024 survey, the State of CSS 2024 survey is open and here is what's new in ECMAScript.In security news, a Microsoft update bricks Linux dual-boot systems, they patched a ...
Dev Digest 131 - AI'm not sure about OSS

From learning to earning

Jobs that call for the skills explored in this talk.