Decision logs people actually read

Every software project makes hundreds of decisions. Which database. Whether to build the admin screens or buy a tool. Why the import runs at night rather than continuously. Why the refund limit is set where it is. A few months later, someone new joins, or someone old forgets, and the same question is asked again. The team either repeats the debate or, worse, quietly reverses a decision without knowing why it was made.

A decision log fixes this. Most teams know that, and many have tried one. Most of those logs are abandoned within weeks, or kept faithfully and never read. The difference between a log that works and one that doesn't is almost entirely about length.

01#Why most decision logs fail

The usual template is borrowed from architecture decision records: context, options considered, decision, consequences, status, related decisions. It is a sensible structure for a large, contested choice. For everyday decisions it is far too heavy.

Two things then happen. Writing an entry takes half an hour, so people stop writing them for anything smaller than a re-platforming. And reading an entry takes ten minutes, so people stop reading them. The log ends up holding six beautifully written records of the biggest decisions and none of the hundred small ones that actually cause confusion later.

The small ones matter. "Why do we store prices in cents?" "Why does the nightly job skip weekends?" "Why is this field optional?" These are the questions that slow a new engineer down, and the answers usually fit in a sentence.

02#The three-line entry

An entry that people will both write and read looks like this:

• →Question: what was being decided, phrased as a question.
• →Call: what was decided, with the date and who made the call.
• →Reason: the single most important reason, in one sentence.

That's it. Three lines, written in under two minutes. For example:

• →Question: Should customers be able to edit an order after it ships?
• →Call: No. 2026-10-23, product owner.
• →Reason: The warehouse system can't accept changes after dispatch, and a half-applied edit is worse than none.

Someone reading this a year later knows what was decided, why, and who to ask. That is ninety per cent of the value of a full record, at a tenth of the cost.

The optional fourth line

For decisions that are likely to be revisited, add one more line:

• →Revisit if: the condition that would make this the wrong call.

"Revisit if order volume passes ten thousand a day." "Revisit if the warehouse system is replaced." This small addition changes how the team treats old decisions. Instead of rules handed down from the past, they become bets with a stated expiry condition. When the condition is met, anyone can reopen the question without it feeling like an attack on whoever made the original call.

03#Where the log should live

The best location is wherever the team already looks every day. A file in the code repository works well for engineering decisions, because it is reviewed with the code and can be linked from a pull request. A pinned page in the team's shared workspace works for product and process decisions. A dedicated tool that nobody opens unless they are writing an entry does not work, however good it is.

Keep one log per product or system, in date order, newest at the top. Resist categories and folders at first. A single searchable list is easier to keep up and easier to read than a carefully organised tree that nobody maintains.

04#Making it a habit

Logs die from neglect, not disagreement. A few habits keep them alive.

Write it within a day

The reason for a decision is clearest in the hour after it is made. A week later it is half-remembered and the entry gets vague. Make it someone's job to write the entry before the end of the meeting or the day. On a small team, that can simply be whoever made the call.

Link to it when the question comes back

When someone asks "why do we do it this way?", answer with a link to the entry. This does two things: it saves you explaining, and it teaches everyone that the log is the first place to look. Within a month or two people start checking it before they ask.

Let entries be superseded, not edited

When a decision changes, don't rewrite the old entry. Add a new one and mark the old one as replaced, with a link. The history of how a team changed its mind is often as useful as the current answer, especially when the same pressures come back.

Review it at handover

When work passes from one team or supplier to another, walking through the log together takes an hour and answers most of the questions a new team would otherwise ask over several weeks. It is one of the cheapest handover documents there is.

05#What doesn't belong

A decision log is not meeting minutes, a task list or a design document. It doesn't need the full discussion, the rejected options in detail, or diagrams. If a decision needs that depth, write the design document separately and link to it from a three-line entry. The log stays short and scannable, and the detail is one click away for anyone who needs it.

The aim is modest: anyone on the team, new or old, can find out what was decided and why in under a minute. Three lines are enough to get there.