slug: adr-writing
title: "Architecture Decision Records -- Documenting the Why"
version: 1.0.0
description: "Document architecture decisions with ADRs—format, lifecycle, and tooling."
category: architecture
tags: [adr, architecture, documentation, decisions, technical-writing]
difficulty: intermediate

xp:
  read: 15
  walkthrough: 40
  exercise: 25
  quiz: 20
  quiz-perfect-bonus: 10

time:
  quick: 5
  read: 15
  guided: 45

prerequisites: []
related: [system-design, technical-debt]

triggers:
  - "What is an ADR?"
  - "How do I document architecture decisions?"
  - "Why should I write ADRs?"
  - "What's the format for an architecture decision record?"

visuals:
  diagrams: [diagram-flow, diagram-mermaid]
  quiz-types: [quiz-drag-order, quiz-timed-choice]
  slides: true

sources:
  - url: "https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions"
    label: "Michael Nygard's ADR Article"
    type: docs
  - url: "https://adr.github.io"
    label: "ADR GitHub Organisation"
    type: docs