Teams

Write the decision down

Decision records for small teams: one page, five headings, written the day you decide. Why they beat a long design doc nobody updates.

Alex Rivera

· 4 min read

An open notebook with a pen and glasses on a white desk

Why bother

Six months from now someone will ask why the app uses a queue here, or why that library was dropped. If the answer lives in a chat thread, it's gone. A short record written on the day you decide is the cheapest documentation a team can keep.

The template

md
# 014: Queue outgoing emailDate: 2026-08-05 · Status: accepted## ContextSending inline made checkout slow when the mail API lagged.## DecisionPush emails to a queue; a worker sends them with retries.## ConsequencesEmails can arrive a minute late. Failures show up in the worker's dashboard.

Number the records and never edit an accepted one. When a decision changes, write a new record that supersedes the old one, so the history stays readable.

Habits that keep it alive

  • Keep records in the repo, next to the code they explain.
  • Link the record from the pull request that implements it.
  • Write it in the meeting, not after it.

Keep reading