I have written before that the decision log is the document I would save first in a fire. Several people asked me to show them exactly what one looks like and how to keep it alive past the initial burst of enthusiasm. This essay is that — a deeper, more practical companion to the broader case for documentation.
A decision log is a single file where you record the choices that outlast the conversation that produced them. That is the whole idea. But the difference between a decision log that compounds for years and one that dies in three weeks is entirely in the details, so let me give you the details.
What a decision actually is
Not everything is a decision worth logging. You do not log "we used blue for the button." You log the choices that someone, six months from now, will be tempted to re-open — usually because they have forgotten why it was settled.
A choice belongs in the log if it has two properties: it took real thought or argument to arrive at, and reversing it later would be expensive or disruptive. "We will bill clients monthly, not per-project." "We will not build our own payments and will use mobile-money rails instead." "We will support offline mode as a first-class feature, not an afterthought." These are decisions. They shape everything downstream, and without a record, they get silently re-litigated every time a new person joins or a hard week arrives.
Log a choice if it took real thought to reach and would be expensive to reverse. Everything else is just preference, and preference does not need a record.
The exact format
I keep it deliberately small. Each entry is four parts, and it fits on half a screen:
- Date and title. When, and a one-line name for the decision.
- What we decided. One or two sentences. The decision itself, stated plainly.
- Why. The reasoning. This is the part future-you is desperate for. Write it for someone who was not in the room and does not trust the decision yet.
- What we considered and rejected. The alternatives, and one line each on why not. This is what stops the decision being re-opened — because the obvious objection is already answered on the page.
That fourth part is the secret. Most logs record what was decided. Almost none record what was rejected and why. But "have we thought about doing X instead?" is precisely the question that re-opens settled decisions, and the rejected-alternatives section answers it before it is asked.
A worked example
Here is a real-shaped entry, lightly anonymised:
2026-02-10 — Billing model for school clients
Decided: Schools pay a flat monthly fee per active student, billed monthly. No per-feature pricing, no annual lock-in.
Why: Schools' income is seasonal and uncertain. A predictable per-student fee maps to how they already think about cost, and monthly billing lets a struggling school leave cleanly rather than defaulting on an annual contract — which protects our reputation more than the locked-in revenue is worth.
Considered and rejected: (1) Annual contracts — better for our cashflow, but trap schools that hit a bad term and generate exactly the disputes we want to avoid. (2) Per-feature pricing — more revenue per school in theory, but every school then argues about which tier they need, and the sales conversation triples in length for no real gain.
Read that and notice: anyone joining the company can now understand not just what the billing model is, but why annual contracts keep getting proposed and keep getting declined. The argument is settled on paper. That is the leverage.
Where it lives and why that matters
The decision log lives in the codebase, as a plain markdown file — decisions.md — committed alongside the work it describes. Not in a wiki, not in a shared drive, not in someone's notes app.
The reason is survival. A document in the repo is seen every time someone opens the project. A document in a separate tool is seen by whoever remembers it exists, which after a month is nobody. The closer the record sits to the work, the longer it lives. Distance from the work is how documentation dies.
What it gives you that nothing else does
Three things, in rough order of when you notice them.
First, in week three, it ends a re-argument. Someone proposes the thing you already rejected, you point at the entry, and a meeting that would have taken an hour takes a minute. This is the first payoff and it is immediate.
Second, in month six, it onboards people for free. A new hire reads the log and absorbs not just the decisions but the judgement behind them — how this company weighs trade-offs. That is culture, transmitted in writing, without a single meeting.
Third, in year two, it becomes an asset you reuse. When a new project resembles an old one, you read the old log and inherit decisions that took weeks to reach the first time. You are no longer solving solved problems. You are starting from your own accumulated judgement.
Start today, badly
Do not design a system. Open a file called decisions.md, put today's date at the top, and write down the three most important decisions your team has made this quarter — what, why, and what you rejected. They will be incomplete and imperfect. It does not matter. The value is not in the first three entries; it is in the chain of them, growing one settled argument at a time, until the day you realise you have not re-fought an old decision in months.