ADR Document Patterns
Learn how to move the needle with docs.
We'll cover the following...
Staff+ engineers leave breadcrumbs through architecture decision records (ADRs). It’s how you say, “Here’s what we did, why we did it, and when we’ll know it’s wrong.”
John doesn’t get promoted for writing more code. He gets promoted for making decisions nobody else can explain. You’re going to flip that script.
What is an ADR?
An architecture decision record (ADR) is a short, structured note, usually 1-2 pages, that captures the reasoning behind a key technical choice. Think of it as a mini design log that turns invisible decision-making into visible alignment.
Each ADR includes:
Problem: What’s the issue or pain point you’re addressing?
Constraints: What limits your options? (Latency, budget, compliance, skills, deadlines.)
Options: At least 2–3 realistic approaches, not just the one you already like.
Decision: Which path you chose, and, crucially, why.
Risks/Consequences: What could go wrong? What tradeoffs did you consciously accept?
Revisit when: The trigger for re-evaluating this decision (metrics, scale, new context).
That’s it. Your ADR should be a 2 minute read—at 2 pages max.
The purpose of the ADR is to leave receipts. Receipts that show you thought carefully, compared tradeoffs, and tied design choices to business needs like a Staff+ engineer.
Example ADR
Problem: Notifications retries are overwhelming the database.
Constraints: Must keep retries under 100ms avg. Latency target = <500ms for 99% of users.
Options:
Store retries in DB table (simple, cheap, risky).
Use Redis as buffer (fast, but no durability guarantees).
Add a message queue + worker pool (reliable, more infra).
Decision: Queue + worker pool
Risks: Queue backlog may grow unbounded → need monitoring + retry caps.
Revisit when: Retry backlog > 100k or queue throughput <1k msg/sec.
AI assessment: Stream distribution
Your team’s video platform is struggling to handle traffic spikes during live events. Viewers report buffering and delays when tens of thousands join at once.
You need to decide how to handle stream distribution efficiently.
Here are your options:
Stream directly from your servers (simple but limited scale).
Use a global CDN for video delivery (fast but expensive).
Implement peer-to-peer (P2P) delivery for viewers (innovative but less predictable).
Say hello to “Ed” in the widget below to get started on your assessment.
Heads up: You will be asked to choose whether you want to be mentored or evaluated first. Choose mentorship if you'd like some coaching along the way.