After several emails about decision records, I should probably say that you don't need to document everything.
I've asked you to save reasoning, define scope, link records and name review triggers. That could start to sound like another task on someone's plate. But it shouldn't be. Useful documentation should reduce work, not create it.
If a designer chooses an established button variant, the design system already explains that choice. Use it. You don't have to create a new decision record saying the team followed an existing pattern.
But suppose the team decides how a chart should summarise a month with missing entries. Should it describe a trend? Warn that the picture is incomplete? Avoid a summary altogether?
Once they make those decisions, the finished screen won't explain why they made each decision. The next people facing the same question will spend days reconstructing that reasoning.
That's a decision worth recording.
Why?
I ask two questions before recording a decision.
- Will someone face this again?
- Could they understand our choice from the finished work alone?
If the question is likely to recur and the reasoning isn't immediately visible, I choose to write a short record. If it's a one-off choice, I'd think twice. Not because these don't deserve a history, they do, particularly when getting it wrong could seriously affect someone's ability to use the product. But because it's unlikely that someone else will come across this in a different context.
It makes no sense to turn every ticket into a decision record. You'll likely start to produce documents to satisfy the process and the useful bits will just be harder to find. Give people room to judge what's worth preserving. The choices that took real discussion, involved a meaningful trade-off or challenged an existing approach are perfect candidates for decision records.
I don't want proof that the team documented its work. I want the next people to have less to figure out.