Every team makes decisions. Most teams forget why they made them. Six months later someone asks “why did we choose PostgreSQL over MongoDB?”, nobody remembers the constraints that applied at the time, and the whole debate happens again, usually with worse attendance.
Decision documents fix that. Call them ADRs, RFCs, or decision logs — the label doesn’t matter. What matters is writing down the context, the options, and the reasoning at the moment of the choice. Running a dev team this year has made me appreciate them more than ever: they’re the difference between institutional memory and institutional folklore.
Why they’re worth the effort#
The obvious payoff is not having the same argument twice. “Didn’t we already decide on the API versioning strategy?” With a clear record of what was decided and why, settled issues stay settled and the team spends its energy on execution instead of retracing its steps.
The quieter payoff shows up over time. Projects run for months or years, people join and leave, and what survives is the code — which tells you what was decided but never why. A decision doc preserves the reasoning: the constraints that existed, the alternatives that were rejected, who made the call. New joiners get context instead of folklore. Cross-team decisions get real buy-in, because everyone can see the factors being weighed rather than just the verdict. And naming a decision-maker and contributors means follow-through has an actual owner.
When to write one#
Not every decision deserves a document. I reach for one when the decision is:
- Expensive to reverse — technology stack choices (frameworks, databases, cloud providers), architectural patterns (microservices vs. monolith, event-driven vs. request-response), third-party vendors, security and compliance approaches
- Long-lived — API contracts that external systems depend on, data models that span services, breaking changes to established patterns
- Cross-team — anything needing buy-in from multiple teams or non-technical stakeholders, resource allocation and prioritisation calls
- The outcome of a spike — when a time-boxed investigation wraps up, capture the findings and the resulting decision before they evaporate
Skip the formality for easily reversible decisions, team-internal implementation details, and anything with minimal impact outside your immediate scope. A document nobody needed is just homework.
The lifecycle#
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Draft │ ──► │ Review │ ──► │ Approved │ ──► │ Implemented │
│ Proposed │ │ Feedback │ │ Accepted │ │ Completed │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ Rejected/ │
│ Superseded │
└─────────────┘The author drafts the problem and the candidate solutions. Stakeholders review — this is the phase that earns the whole exercise, because it’s where assumptions get challenged and blind spots surface. A decision-maker (usually a tech lead, architect, or product owner) makes the final call, the team implements, and the doc gets updated if reality forced changes along the way. Some documents die in review; others get superseded later as circumstances change. Mark both clearly, because a stale “accepted” doc is a trap for whoever finds it next.
What makes one worth reading#
Start with the problem, not your favourite solution. What are we solving, why does it matter now, and what happens if we do nothing? If people don’t agree on the problem, debating solutions is theatre.
Then present real options — at least two or three, even when you have a strong preference. For each one: a brief description, pros and cons, a rough effort estimate (T-shirt sizing is fine: S/M/L/XL), and the risks with how you’d mitigate them. Documenting the alternatives is how future readers understand why the winner won.
Name the trade-offs out loud. “We’re choosing speed-to-market over architectural purity.” “We’re accepting increased operational complexity for better scalability.” “We’re prioritising developer experience over raw performance.” Sentences like these do more for a future reader than pages of analysis.
Ground the discussion in something concrete: code snippets showing how a solution would look, diagrams of the system interactions, links to proof-of-concept work from spikes. Abstract discussions produce abstract decisions.
Finally, give it a deadline — when the decision must be made, who owes input by when, and what’s blocked while it drifts. Decisions without deadlines drift forever.
Example: Architecture Decision Record (ADR)#
Here’s a practical example of a decision document:
# ADR-001: API Authentication Strategy
**Status:** Accepted
**Date:** 2024-11-15
**Decision Maker:** Sarah Chen (Platform Architect)
**Contributors:** Backend Team, Security Team, Mobile Team
## Context
Our public API currently uses API keys for authentication. As we expand to
support third-party integrations and mobile apps, we need a more robust
authentication mechanism that supports:
- Token expiration and refresh
- Scoped permissions
- User-level authentication (not just service-level)
## Decision
We will implement OAuth 2.0 with JWT tokens for API authentication.
## Options Considered
### Option 1: OAuth 2.0 with JWT (Recommended)
**Description:** Industry-standard protocol with self-contained tokens
| Pros | Cons |
|------|------|
| Industry standard, well-documented | More complex initial implementation |
| Self-contained tokens reduce database lookups | Tokens cannot be revoked instantly |
| Broad library support | Requires refresh token management |
**Effort:** Medium (2-3 sprints)
### Option 2: Session-based Authentication
**Description:** Traditional server-side sessions with cookies
| Pros | Cons |
|------|------|
| Simple to implement | Not suitable for mobile apps |
| Easy to revoke sessions | Requires sticky sessions or shared session store |
| Familiar to most developers | Doesn't scale as well |
**Effort:** Small (1 sprint)
### Option 3: Custom Token System
**Description:** Build our own token-based authentication
| Pros | Cons |
|------|------|
| Fully customizable | Reinventing the wheel |
| No external dependencies | Security risks from custom implementation |
**Effort:** Large (4+ sprints)
## Consequences
- Mobile team can implement standard OAuth flows
- We'll need to set up a token refresh mechanism
- API documentation will need updates for OAuth flows
- Existing API key users will need a migration path (6-month deprecation)
## References
- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749)
- Internal spike document: [Authentication Options Spike](/spikes/auth-spike-2024)
- Security team review: SEC-2024-042A template to steal#
Use this as a starting point and trim it to fit your team:
| Attribute | Details |
|---|---|
| Decision/Issue Name | [Clear, descriptive title] |
| Status | [Draft / In Review / Accepted / Rejected / Superseded] |
| Impact | [High / Medium / Low] |
| Owner | [Name of the person driving the decision] |
| Decision Maker | [Person with final authority] |
| Due Date | [Deadline for making the decision] |
Problem Statement#
What problem are we solving? Why does it matter? What’s the cost of inaction?
Background#
Provide context, history, and any relevant details. Link to related documents, previous decisions, or spike results.
Constraints#
What limitations or requirements must any solution respect?
- Budget constraints
- Timeline requirements
- Technical constraints (existing systems, skill sets)
- Compliance or security requirements
Solutions Considered#
| Option | Description | Pros | Cons | Effort | Risk |
|---|---|---|---|---|---|
| Option 1 | Description | Pro A, Pro B | Con A, Con B | S/M/L/XL | Low/Med/High |
| Option 2 | Description | Pro A, Pro B | Con A, Con B | S/M/L/XL | Low/Med/High |
| Option 3 | Description | Pro A, Pro B | Con A, Con B | S/M/L/XL | Low/Med/High |
Recommendation#
State your recommended option and summarize why it’s the best choice given the constraints and trade-offs.
Decision#
Document the final decision once made. If different from the recommendation, explain why.
Consequences#
What are the implications of this decision? What follow-up work is required?
Action Items#
| Action | Owner | Due Date |
|---|---|---|
| Action 1 | Name | Date |
| Action 2 | Name | Date |
References#
Links to related documents, external resources, spike results, or prior decisions.
Making the habit stick#
Store the docs somewhere consistent — a dedicated folder in the repo, a wiki space — because a decision nobody can find might as well not exist. Keep them lightweight; a document that takes days to write won’t get written. Reference them from code comments, commit messages and pull requests, so the “why” stays attached to the “what”. When a decision is superseded, don’t delete the old doc — mark it superseded and link to the new one; the history is the point. And revisit old decisions in your retrospectives: which ones held up, which you’d make differently now.
The failure modes are just as predictable. Analysis paralysis: set a deadline, decide with the information you have, and remember most decisions can be revisited. Rubber-stamp reviews that never produce real critique add process without adding value. Orphaned documents that never lead to action are worse than no documents at all. Too much detail: the doc should cover the why and the what, not the how — implementation belongs in technical specs. And when stakeholders disagree, write the dissent down. The decision may stand anyway, but the objection is exactly the context someone will need a year from now.
Start with your next significant decision. Write it up, even if it’s rough, and refine the process as you go. Every “why did we choose X?” meeting that doesn’t happen because someone just read the ADR is an hour your team gets back.
Further Reading#
Related Articles on This Site:
- Understanding Spikes in Agile Software Development - gather information with a spike before making the big call
- Retrospectives: The Power of Feedback Loops - review past decisions as part of continuous improvement
- Planning an API - decision-document thinking applied to API design
- GitHub for Project Management - keep decision documents next to your code
External Resources:
- Documenting Architecture Decisions - Michael Nygard - the original post that popularised ADRs
- ADR GitHub Organization - tools, templates and examples for Architecture Decision Records
- Design Docs at Google - how Google approaches design documentation
- RFC Process at Rust - a well-documented RFC process from the Rust language
- Spotify’s Decision Record Template - Spotify’s take on when to write an ADR