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-042

A template to steal

#

Use this as a starting point and trim it to fit your team:

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

#

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

#

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

Why they gave up on meetings

#

Their starting point will sound familiar. Nobody comes prepared, the meeting starts late, and the loudest voice wins whether it’s right or not. An hour later you’re more confused than when you walked in and wondering if there’s any paracetamol left in the drawer.

Alan tried fixing meetings first — 15 minutes max, clear agenda, decision required. It didn’t hold. Discussions drifted, nobody could remember what was said, and absent or remote people were simply out of luck. So they moved the whole thing into writing.

The claims they make for it ring true to me. Writing forces you to slow down and actually think, so the discussion gets more nuanced and better argued. Everything is documented instead of half-remembered. It stops being an eloquence contest. And because the forum is open to the whole company, anyone can contribute — not just whoever happened to be in the room.

GitHub as the company forum

#

The forum itself is GitHub, a platform built for code review that Alan cheerfully hijacked. The setup is almost embarrassingly simple:

1. Create a GitHub account.
2. Create a private repo with no code in it (theirs is called “Topics”).
3. Add a labelling system to categorise conversations.
4. Use the Issues tab: open issues are live discussions, closed ones are decisions made.

They’ve passed 17,000 issues. That’s a lot of meetings that never had to happen, and — the part I find most appealing — a searchable history of why every decision went the way it did. If you want to challenge an old decision, you can first read which arguments won last time.

When to open an issue

#

Not every decision earns an issue. Their filter is four questions: who will be affected? how reversible is it? how urgent is it? do I need more context before deciding?

Broadly, high-impact and hard-to-reverse decisions go to the forum; the rest can stay in Slack. They lean on the one-way vs two-way door distinction: a one-way decision (too expensive or painful to reverse — their example is a price increase) gets the full written treatment, while a two-way decision (cheap to undo, worst case you lose some energy) doesn’t need the ceremony.

LOCI: who does what

#

Every discussion assigns roles using the LOCI model — Lead, Owner, Consulted, Informed.

The Lead is accountable for the decision’s success and makes sure the context is understood across the team. They say upfront how involved they want to be, then trust the Owner and take responsibility for what the team produces, speaking up only when they strongly disagree. One Lead per discussion.

The Owner makes the final call and drives the project. They keep contributors informed and contributing on time, investigate the problem, open and close the issue, and share the decision. If they hit a wall they can’t get past, they go to the Lead. One Owner per decision.

Consulted people are the ones whose input genuinely matters to the trade-off. They’re expected to contribute promptly — even if only to say “nothing to add” — and to raise the alarm (escalating to the Lead if needed) when they think the decision is badly wrong. Alan caps this group at about six, because more input starts costing schedule.

Informed people simply get told, usually once the decision is made. One-way communication, nothing expected back. The Owner decides who’s affected enough to be notified.

That works decision by decision. For a whole project, I write the same thing down once, as a project communication plan: who needs to hear what, how often, and who tells them.

The anatomy of an issue

#

Every issue uses the same template, which both sharpens the thinking and quietly teaches junior people how to break a problem down:

• Scope — the “why” of the discussion, including the underrated line “this issue is NOT about…”
• Context & materials — links to prior discussions and documents
• LOCI — who’s Lead, Owner, Consulted, Informed
• A deadline — when to contribute by, when the issue closes, when a solution is needed
• A solution proposal — one suggested answer, or options to choose between
• Questions — aimed at specific people to confirm or refute specific assumptions, so the issue isn’t a message in a bottle

Writing rules that keep things moving

#

A written debate can drag just as badly as a spoken one, so they have rules. Be concise — they quote Boileau: “What is well conceived is clearly stated.” If you can’t write it simply, you’re not actually sure of it yet. Apply the “So what?” test to everything you write; if the implication of your comment isn’t obvious, spell it out.

For the Owner, the follow-up matters as much as the opening. Keep the discussion pointed at the million-dollar question — the one sticking point that actually matters — rather than letting it dissolve into details. Recap regularly what’s been agreed and what’s still open. And treat Slack reminders as a last resort, reserved for overdue contributions or genuine urgency.

Owners also hide comments that don’t move the conversation forward, and everyone is expected to know their way around GitHub’s formatting — headings, footnotes, tables, keyboard shortcuts — because in writing, form carries almost as much as substance.

No consensus, no spectators

#

Two rules stop this from turning into decision-by-committee.

First, the Owner decides as what Alan calls an “enlightened despot”. They investigate ideas, measure risks, question peers — but they don’t seek consensus and they don’t have to implement everything they’re told. Alan is blunt about not being a democracy: every employee is a shareholder, and the company’s interest comes before the team’s or the individual’s. When the Owner is reasonably sure of the right bet, they decide, everyone tries it, and once the impact is visible they review whether it was the right call.

Second, contributor numbers are controlled. Jeff Bezos’ two-pizza rule applies to async work too: the more people on an issue, the less each one contributes. Past about six contributors, the spectator effect kicks in and participation quality drops. Notifications follow the same philosophy — Alan trusts everyone to have configured their own GitHub notifications (Settings, then tick “Web and Mobile” under both “Participating” and “Watching”), so direct tags in the Questions section are kept to a minimum.

What I’m taking from it

#

You can never fully explain a meeting to someone who wasn’t there, but anyone can read a decision. Alan doesn’t claim this is the best or only system — just the one that fits them: fewer interruptions, less spectator effect, and decisions made with a step back and the facts written down. I’m not about to move every decision my team makes into GitHub issues, but the template below is going straight into our repo.

The template, as a GitHub issue template

#

Save this as .github/ISSUE_TEMPLATE/decision.md in whichever repository you use as the forum, and GitHub offers it every time someone opens a new issue. The sections are Alan’s; the LOCI lines and the label are my additions.

---
name: Decision
about: Propose a decision and collect input in writing
title: "[Decision] "
labels: decision
---

## Scope
- The goal of this issue is ...
- This issue is NOT about ...

## Why I'm opening this issue

## LOCI
- Lead:
- Owner:
- Consulted:
- Informed:

## Timeline
- Contributions by:
- Decision by:

## Context and materials

## Proposal

## Questions

GitHub Issues or GitHub Projects?

#

If you’re thinking about GitHub for project management more broadly, the two pieces do different jobs. Issues hold the discussion and, once closed, the decision. A GitHub Project is a board or table laid over issues from one or more repositories, with your own fields for status, owner or deadline. For a decision forum like Alan’s, labels and the issue list are enough. Add a Project when you want every open decision on one screen, sorted by the date it has to be made, and when you start tracking delivery work in the same place, which is where most teams end up using both.

Why do people want the things they want? I think about this more than I expected to. When I first wrote this I was working on a platform where people spent all day discussing cosmetics, and why one product got coveted while a nearly identical one sat ignored was basically the whole business. Taste is personal, sure, but the patterns underneath it are surprisingly consistent.

Desirability, feasibility and viability

#

The three-lens version comes from design thinking, and it’s become a common way for product teams to check an idea before they commit to it. The useful part is that the three fail in different ways. A feasible, viable product nobody wants is the classic startup failure: well engineered, sensibly priced and ignored. A desirable product that can’t be built, or can’t make money, at least fails for a reason you can see coming.

Desirability is the one teams most often skip, because it’s the hardest to measure and the easiest to assume. Everyone on the team already wants the thing they’re building. That tells you nothing about anyone else.

The rest of this post is about what desirability is made of, and then how to check for it.

It has to work, and keep working

#

Desire usually starts with plain usefulness: the kitchen gadget that genuinely saves you ten minutes, the phone that just keeps you connected. But utility on its own only gets you to “fine”. The things people actually covet do their job exceptionally well, and keep doing it. Quality and durability are what turn a purchase into a possession someone defends, like a classic car or a knife that outlives its owner. Nobody lusts after something they expect to break.

It has to make you feel something

#

Aesthetics pull harder than we like to admit. The lines of a sports car or the plating of a good dish grab you before the rational part of the brain gets a vote. And the strongest wants are emotional ones: joy, nostalgia, belonging. A battered childhood toy fails every practical test and is still impossible to throw away. Personalisation feeds the same instinct. Something tailored to you feels like yours in a way the stock version never will.

Other people decide more than we’d like to think

#

Desirability is partly a social construct. Trends, peer approval and cultural norms quietly steer what we want. Scarcity does too: limited editions, rare stones, one-off pieces. Rarity signals that wanting this thing puts you in a small club. Reputation then compounds everything. Glowing reviews and word of mouth make a thing feel safe to want. On that cosmetics platform I watched this loop run every single day: one well-liked reviewer, a short-run product, and a week later it was sold out.

The maths still has to work

#

Price doesn’t kill desire, but a bad deal does. People happily pay a premium for luxury and still walk away from anything that feels like poor value for hard-earned money. And increasingly, values sit inside the same calculation. Whether something was made sustainably and ethically now moves it up or down the wish list for a lot of people. Me included.

How to test whether something is desirable

#

The trap with desirability is that asking people directly doesn’t work. “Would you use this?” gets a polite yes from almost everyone, because saying yes costs nothing. The tests that work all ask people to give something up, like time, money, an email address or a habit, and watch whether they do.

Ask about the past, not the future. “Tell me about the last time you had this problem, and what you did about it” gets you real behaviour. If nobody can remember the last time, the problem isn’t painful enough to want a solution for.

Put up a fake door. A landing page, or a button in an existing product, for something that doesn’t exist yet, and count how many people click through or leave an email. It feels slightly cheeky, but it’s the cheapest honest signal there is. Be upfront on the other side of the door that it’s coming soon.

Ask for a commitment. A waitlist is weak, a pre-order or deposit is strong. People will sign up for anything, but they only pay for what they want.

For something people already use, ask how they’d feel if they could no longer use it. A common rule of thumb in product circles is that if around 40% of your users would be “very disappointed”, you’ve got something people genuinely want. It’s a crude measure, but it’s far better than asking people whether they like it.

And watch what people do rather than what they say. Which features get used a second time, which ones people come back to without a reminder, what they complain about when it breaks. Complaints are underrated here. Nobody complains about losing something they didn’t want.

Putting it together

#

None of these traits carries a product on its own. But stack a few of them, so that it’s genuinely useful, well made, good to look at, a little scarce and vouched for by people you trust, and you get the things people queue for. Most of the rest is marketing.

In short

#

Desirability is how much people want something, beyond whether they need it. In product terms it’s the “do people want this?” lens that sits alongside feasibility and viability. It comes from usefulness that lasts, an emotional or aesthetic pull, social proof and scarcity, and a price that feels fair. You can’t find it by asking people whether they’d use something. Test it by asking them to give up something real, and watch what they do.