How to Document Decisions at Work

The cheapest way to document a decision at work is a four-line markdown entry written the same day: name the choice, the reason, the owner, and what changes. Add the date. That entry is a decision log. It takes two minutes, lives in a plain text file, and ends the meeting where the team re-decides what it already decided.

The discipline has a name and a body of evidence behind it. McKinsey's 2019 study of more than 1,200 managers found that 61 percent of respondents say at least half the time they spend making decisions is ineffective — opportunity costs the firm put at about 530,000 days of managers' time per year for a typical Fortune 500 company, equivalent to some $250 million in wages annually ¹. A decision log will not make the decisions better. It will stop the organisation from making the same one twice — the meeting Atlassian's State of Teams 2024, a survey of 5,000 knowledge workers and 100 Fortune 500 executives, found costly enough that "in organizations with poor meeting cultures, people spend 50% more time in unnecessary meetings than making progress on high-priority work." ² The rule every senior engineer eventually learns is a saying at August, a business-transformation consultancy: "If it's not written down, it isn't decided." ³

The single habit that makes decision documentation work

Write the decision down the day the team makes it, in plain text, in the place the team already looks. One entry, four facts: the decision in one active-voice sentence, the reason, the owner, the consequence. Everything else — review meetings, approval chains, tooling — is optional. A team that captures the minimum already outperforms a team that captures nothing.

The reason the habit matters is that work does not record why. AWS's prescriptive guidance, written by Darius Kunce and Dominik Goby in March 2022, names the two failure modes plainly. The first: "A decision is made without any justification, and people don't understand why it was made. This results in the same topic being discussed multiple times." ⁴ The second is worse: "The decision isn't captured in an architectural decision repository, so team members forget or don't know that the decision was made." ⁴ A written decision closes both gaps with a file the size of a tweet.

Joel Spolsky gave the deeper reason in April 2000, in one sentence: "It's harder to read code than to write it." ⁵ The principle generalises past code. A shipped feature, a signed vendor contract, a chosen process — each is the output of a decision. The inputs were the alternatives the team rejected and the constraints that mattered that morning. None of those survive in the artefact. The decision record is the only place they get written down.

The five-minute version

The five-minute decision record is the one you write when the team is busy, which is always. It is four lines in a shared markdown file, written before the meeting ends: the decision, the reason, the owner, the consequence. Speed is the point. A record that takes thirty minutes to write does not get written at all.

Open one running file — call it decisions.md — and append a dated entry, the same way a daily note works as an append-only log. The structure is fixed so the team never debates format mid-meeting:

## 2026-06-03 — Drop the staging environment

**Decision:** We will retire the shared staging environment and
test against per-branch preview deploys instead.

**Why:** Staging drifted from production weekly; preview deploys
match production and cost less to run.

**Owner:** Dana

**Consequence:** Faster feedback per pull request; one-time
migration of three CI jobs; no shared QA sandbox after June 30.

That is the whole record. A heading with an ISO-8601 date, a one-sentence decision in active voice, a one-sentence reason, an owner, a consequence. The active voice is not decoration — "We will retire" is auditable in a way that "it was decided that staging would be retired" never is. Microsoft's engineering playbook frames the payoff of a dedicated log in one line: "It is easier to find the design decision in a log than having to read a large document." ⁶

The five steps fit on an index card:

1. Open the team's running decisions.md (or a new file decisions/2026-06-03-drop-staging.md). 30 seconds.
2. Add a heading: the date, then the decision as a noun phrase. 30 seconds.
3. Write the decision in one active-voice sentence: "We will …". 1 minute.
4. Write one sentence of reason and name one owner. 2 minutes.
5. Write one line of consequence — what gets easier, what gets harder. 1 minute.

Five minutes, start to finish. The honest cost is not the writing; it is the discipline of doing it before the room empties. Spotify's engineering team, writing in April 2020, defined the artefact precisely: "An Architecture Decision Record (ADR) is a document that captures a decision, including the context of how the decision was made and the consequences of adopting the decision." ⁷ A decision log is the same idea, stripped to the part any team — engineering or not — can keep.

The thirty-minute version

The thirty-minute version is the one you write when getting the decision wrong will cost months. It is the same four facts, expanded with the alternatives you rejected and the criterion that will tell you later whether you were right. Default to the five-minute version; reach for this one when the decision is expensive to reverse.

The expanded record adds three sections to the spine: the options considered, the trade-offs accepted, and a confirmation criterion — a measurable way to know, six months on, whether the decision held. The hoop.app guide names what a full record carries: a decision log "memorialize[s] the who, what, why, when, and where surrounding a decision so that current and future employees can learn, plan, and move work forward with confidence and clarity." ⁸ The expanded entry reads like this:

## 2026-06-03 — Choose the analytics vendor

**Decision:** We will adopt Vendor A for product analytics.

**Why:** Self-serve event tracking without a data-engineering
hand-off; fits the $400/month budget; EU data residency.

**Options considered:**
- Vendor A — chosen; cheapest with EU residency
- Vendor B — richer dashboards, twice the price, US-only
- Build in-house — rejected; six engineer-weeks we do not have

**Owner:** Priya · **Consulted:** legal, data team

**Consequence:** Marketing self-serves dashboards; one new
data processor in the GDPR register; vendor lock-in on event
schema.

**Confirmation:** Revisit in Q1 2027. The choice held if three
teams ship dashboards without a data-engineering ticket.

The confirmation line is the section most teams skip and the one that pays off most. Without it, the record is a snapshot of an opinion. With it, the record is a hypothesis the next team can test. McKinsey found that respondents who reported their decision making was fast were 1.98 times more likely than others to report good decisions ¹ — and speed comes from not re-arguing settled questions, which is exactly what a confirmation criterion protects.

For decisions that are specifically architectural — a database choice, a framework, a storage model — this thirty-minute record graduates into a formal Architecture Decision Record, with its own numbered file and immutable history. That format has fifteen years of convention behind it; the dedicated guide on Architecture Decision Records covers the numbering, the MADR template, and the supersession rules in full.

Common mistakes

Most teams that try to document decisions and then quit do so for the same five reasons, and each one quietly collapses the practice back into the silence it was meant to fix. None of these mistakes is about effort. Every one is about where the record lives, when it gets written, and who it is written for.

• Writing the record as compliance. If the only reader is a process auditor, the entry is a chore and the team abandons it by month two. The reader is the colleague who joins in 2027 and asks why. Write for that person.
• Writing it after the fact. A retrospective record loses the alternatives — by the time the postmortem runs, nobody remembers what the team almost did instead. Write before the decision ships, not after it breaks.
• Skipping the consequence line. "What becomes easier or more difficult?" is the hardest prompt and the most useful one. A record without consequences documents a choice without its trade-offs, which is precisely the failure decision logs exist to fix.
• Burying it where nobody looks. A decision in a private doc, a closed Slack thread, or a meeting recording is not documented — it is hidden. Keep the log in the one place the whole team already opens.
• Letting the format drift. When every entry has a different shape, the log stops being scannable and becomes another large document. Fix the four fields — decision, reason, owner, consequence — and never negotiate them in the meeting.

The buried-decision mistake is the quiet killer. The AWS guidance describes the result of a decision nobody can find: "team members forget or don't know that the decision was made." ⁴ A log that lives next to the work travels with every clone, every backup, every new hire's first day. A decision trapped in a meeting recording dies with the calendar event.

How this works in MNMNOTE

A decision log is a single markdown file, which is exactly what MNMNOTE is built to keep. Open mnmnote.com, start a note called decisions, and append a dated entry each time the team settles something — no account, no install, the notes stored locally in your browser, on your own device.

Wiki-link syntax — [[2026-06-03-drop-staging]] — connects each decision to the spec or meeting note that produced it, so the reasoning shows up as backlinks. The file is plain markdown, so it opens in any editor your team already uses. Steph Ango's rule holds: "In the fullness of time, the files you create are more important than the tools you use to create them. Apps are ephemeral, but your files have a chance to last." ⁹ A decision log is the most durable note a team can keep.

Frequently Asked Questions

These are the questions that surface every time a team tries to start documenting decisions. The answers are the honest version, written for the person who has read this far and is deciding whether the habit is worth the friction. The short answer: it is, and the friction is smaller than one re-litigated meeting.

What is a decision log?

A decision log is a single document — usually a plain markdown file — where a team records each decision the day it is made. Each entry names the decision, the reason, the owner, and the consequence. The hoop.app guide calls decision logs "team and companywide sources of truth for important decisions," memorialising "the who, what, why, when, and where surrounding a decision." ⁸

How do you document a decision at work?

Write four facts the day the decision is made: the choice in one active-voice sentence, the reason, the owner, and the consequence. Add an ISO-8601 date. Append it to a shared markdown file the whole team can open. The entry takes about two minutes for a routine decision — written before the meeting ends, not after.

What is the difference between a decision log and meeting notes?

Meeting notes capture everything discussed; a decision log captures only what was decided. The two are complementary. Meeting notes are the transcript of the conversation; the decision log is the distilled outcome, searchable on its own. Many teams keep a meeting notes template that feeds a single line into the decision log whenever the meeting actually settles something.

Where should we keep the decision log?

In the one place the whole team already looks each day — the source repository for engineers, a shared markdown file or wiki for everyone else. Microsoft's engineering playbook makes the case: "It is easier to find the design decision in a log than having to read a large document." ⁶ Avoid private docs, where decisions go to be forgotten.

Why do teams keep re-deciding the same things?

Because the original decision was never written down, or was filed somewhere nobody can find. AWS names the failure mode directly: a decision made without recorded justification "results in the same topic being discussed multiple times." ⁴ McKinsey put the cost at roughly $250 million in wasted wages annually for a typical Fortune 500 company ¹.

Do small teams really need to document decisions?

Yes, often more than large ones. On a small team, the per-person cost of forgetting why a choice was made is higher, because fewer people remember. On a team of one, future-you is the next team member — and you have already forgotten why you picked the vendor you picked. The two-minute entry is cheap insurance.

How is this different from an Architecture Decision Record?

An Architecture Decision Record (ADR) is a decision log entry formalised for architectural choices — numbered, immutable, stored next to the code. A general decision log is lighter and works for any decision: vendor, process, hiring, roadmap. Use a plain decision log for everyday calls; graduate to the ADR format when the decision is architectural and expensive to reverse.

How long should a decision record be?

Four lines for a routine decision; a paragraph for an expensive one. The five-minute version captures decision, reason, owner, and consequence. The thirty-minute version adds the options considered and a confirmation criterion. Longer than that and the record stops being scannable. Spotify reported that "ADRs have made it easier for teams to align on best practices across Spotify." ⁷

The record outlasts the meeting

Document one decision a day for thirty days, and the next time someone reopens a question the team already closed, you will paste a four-line entry instead of scheduling an hour. The decision was the expensive part; writing it down is the cheap part that makes the expense count. Write today's decision before the room empties.

A meeting that ends without a written decision did not end; it merely paused.

References