How to document decisions without building bureaucracy

The email that reopened a decision from March

A client I looked after on a small maintenance retainer emailed me one autumn morning with a fair question. A new member of their staff had noticed that customers did not get a PDF invoice attached to their order confirmation, and wanted to know why I had never built it. The tone was polite and slightly puzzled, the way people write when they assume something was forgotten.

It had not been forgotten. We had decided against it on a call in March, because their accounting software already sent invoices separately and two PDFs for one order would confuse customers. I remembered the call clearly. What I did not have was anything in writing. No ticket comment, no line in the shared brief, nothing I could paste.

So we argued it again. Not angrily, but it took most of an afternoon: a couple of emails, a short call, the new staff member explaining their view, me explaining a reason I could only describe from memory. In the end someone checked the accounting settings and the original reason held. We landed exactly where we had been in March, minus an afternoon each and with the new staff member slightly wary of me.

That afternoon is what an undocumented decision costs. Not a disaster, just the same conversation again, with less trust the second time. Since then I write a short note for any decision that someone outside the call will one day question. It takes about two minutes, and it is the least bureaucratic thing I do all week.

That afternoon is what an undocumented decision costs.

Five fields, and nothing that does not earn its place

The fear with documentation is that it grows. Somebody proposes a decision record, someone else adds a template with fourteen fields, and within a month nobody fills it in. Bureaucracy is process without payoff. What I aim for instead is a record small enough that writing it costs less than one repeated argument.

The smallest version that works has five parts: context, options, the decision, owners, and a revisit trigger. Half a page at most, linked from the ticket or task where the work happens. Chat is where the conversation starts. The note is where it ends, and the place you point to next time instead of explaining again.

Which conversations deserve a note

Most do not. I promote a thread or a call into a written decision when any of these is true:

• It affects other people or another team.
• It is hard or expensive to undo: an API shape, deleting data, pricing logic.
• People who were not there will need the reasoning.
• The same debate has already happened once.
• The spec is changing while people argue in the thread.

Skip it for small preferences that are easy to reverse. A feature flag you can flip back can live in a pull request description. My PDF invoice question would not have needed a long record, just two lines. It qualified on the third and fourth bullets: someone not in the call would eventually ask, and it had already been discussed.

Graduating a thread takes five minutes. Write a short comment or page. Paste the conclusion, not the whole argument. Link the original thread in case anyone needs the history. Answer the next question about it with the link. Name one person who keeps it current. Where those notes should live so they do not turn into a second notes system is a separate question, which I cover in useful work notes.

Decision log template (copy into the ticket)

## Decision: [one-line title]
Date: YYYY-MM-DD
Status: Accepted | Deferred | Superseded by [link]

Context:
[One paragraph: problem and constraint]

Options considered:
1. ...
2. ...
3. ...

Decision:
[What we chose - first sentence is the choice]

Why / tie-breaker:
[Cost, risk, time, or user impact - say it explicitly]

Owners:
Execute: [name]
Revisit authority: [name]

Revisit trigger:
[Date, metric, or event - e.g. "Q2 planning" or "support tickets > N/week"]

Links:
Work item: ...
Chat/meeting: ...
Related decisions: ...

The first sentence under Decision should be the choice itself, because many readers stop there. The rest is for whoever has to implement it or challenge it. When a decision changes, add a "Superseded by" line and link the new one. Do not delete the old record. Being able to see that a team changed its mind, and why, is worth more than a tidy page.

The same template, filled in by a team

## Decision: Checkout tax via TaxService, not inline cart math
Date: 2026-09-12
Status: Accepted

Context:
Cart calculates tax inline; finance spreadsheet disagrees on two EU rates; support tickets rising.

Options considered:
1. Keep inline math and patch rates monthly
2. Call TaxService for all carts (chosen)
3. Hybrid: TaxService for EU only

Decision:
All carts call TaxService; inline math removed behind flag tax_service_v1.

Why / tie-breaker:
One source of truth beats faster inline path; EU ticket volume is the pain.

Owners:
Execute: Sam
Revisit authority: Priya (platform)

Revisit trigger:
Error rate on tax_service_v1 > 0.5% for 7 days, or finance rejects sample orders.

Links:
Epic CHECK-220; thread #checkout 2026-09-11; ADR not required at team size.

Without a record like that, what usually happens is that product hears "we use TaxService now" in a call, while the mobile developer, who was not in that call, keeps building against the old inline maths for a week. Nobody did anything wrong. The decision simply never reached the place the mobile developer looks.

The line that does the most work is "Why / tie-breaker". When two options are close, the reason one won tends to live in someone's tone of voice in a meeting. Six months later the tone is gone, the options look equal again, and the argument restarts. Write the tie-breaker as a plain sentence: cost, risk, time or user impact. A record should answer a stranger's question, "what did you pick, and what did you reject?" A record that only says a meeting happened will not prevent the next one.

Closing a call with a decision, not a mood

Plenty of decisions start as a written proposal and never need a call at all. The author posts context, options, a recommendation and an "objections by" date. People object with reasons. The owner marks it accepted and links it from the ticket. A meeting is only needed when the objections are substantial, and the case for keeping those rare is in running fewer and better remote meetings.

When a call does happen, the last five minutes belong to the note. Either the decision draft is written before people leave, or it is not decided. On one team we rotated a "closer" role for this: whoever held it that week stopped the discussion at the five-minute mark and typed the decision, or an explicit "deferred until Thursday" with a name. The temptation is to skip it when everyone is tired after a long call. That is exactly when the two-minute record matters most, because tired people remember the call differently.

Reversals should be written too, especially by whoever has the most authority. A lead who changes a decision in writing, with a reason, builds more trust than one who quietly lets the old decision fade.

What bad and good records look like

The quality bar is simple: could someone in another time zone pick up the work tomorrow with only the ticket and the linked note? If not, something is missing, and adding it is not bureaucracy.

Client work and pull requests

For freelance work, I now put client-visible decisions on the shared brief or the ticket the client can see: scope cuts, timeline changes, technical choices they approved. I paste their approval line word for word, with the date. "Decision: no PDF invoice in order emails, because the accounting tool sends invoices separately. Agreed on the call of 14 March." If I had written that sentence in March, the autumn email would have taken one reply.

On engineering teams, a merged pull request description can carry the record for code-level choices: what changed, what was rejected, what follows. Reviewers can hold the line here. A change in behaviour, or a flipped default on a config flag, should not merge without a sentence of context and a link to the ticket.

When folklore is already thick

If a team re-argues the same few choices every month, a half-day harvest helps. List the arguments that keep coming back, using chat search and retro notes. For each, write a five-field record from memory as best you can, and mark unknowns honestly rather than guessing. Link each record from the live ticket or README so the next debate starts at the link. Give each one an owner and a revisit trigger, so "we will revisit later" has a date. Stop when the top five have records. The goal is to stop the repeats, not to document the whole history of the team.

Tools do not replace the sentence. A neat wiki tree or a database of decisions only helps if the ticket links to the canonical record. Otherwise you have two archives and nobody sure which one is true.

A good test for new joiners: ask them to find one decision from last month and explain it without asking anyone. If they cannot, fix the habit before adding any templates. And two-person teams forget as easily as big ones; thirty seconds in the shared task list beats an afternoon of reconstructing a call. Every decision you leave undocumented is a meeting you have already booked for some morning months from now. Write the sentence while you still remember why.