Here's what happens when decisions aren't documented:
Six months from now, someone faces a problem. They think about it. They explore options. They make a decision.
They don't know you already made that exact decision. You had reasons. You considered alternatives. You knew things about the context.
They make a different decision. Maybe better, maybe worse. Probably inconsistent with what already exists.
Now you have two approaches to the same problem in the same system. Future developers are confused. The codebase is incoherent.
All because the original decision wasn't written down.
The Decision Tax
Every undocumented decision imposes a tax:
**Rediscovery tax.** Future people will encounter the same decision point. They'll spend time thinking about something already thought through.
**Inconsistency tax.** Without the original reasoning, they might decide differently. The system becomes inconsistent.
**Archaeology tax.** When something breaks, people dig through code trying to understand why it was built that way. If the decision was documented, this would take minutes. Without documentation, it takes hours.
**Onboarding tax.** New team members need to understand why things are the way they are. Undocumented decisions mean asking around, getting incomplete answers, or just accepting mystery.
You pay these taxes forever. Every time someone hits the decision point. Every time something related needs to change.
The Documentation Objection
"We don't have time to document decisions."
Here's the math:
Time to document a decision: 5-15 minutes Time to rediscover, debug, or reverse a decision: Hours to days Number of times people will encounter the decision: Many
The documentation time is trivial compared to the cumulative cost of not documenting.
"We'll document later."
No you won't. Later, the context is gone. You don't remember why you decided what you decided. The documentation will be thin or wrong.
Document when the decision is made. Context is fresh. It takes minutes.
What to Document
Not every decision needs heavy documentation. A lightweight approach:
**What was decided.** The choice made. Clear and specific.
**Why.** The reasoning. What factors drove the decision.
**Alternatives considered.** What else was on the table. Why those weren't chosen.
**Who decided.** Who owns this decision if questions arise.
**When.** Date. Allows historical context.
That's it. Five fields. Two minutes to fill out.
For significant decisions, you might add more: risks accepted, dependencies, expected consequences. But even the lightweight version beats nothing.
The Format Doesn't Matter
ADRs (Architecture Decision Records) are one format. But don't let format debates delay action.
Use a markdown file. Use a spreadsheet. Use a Notion page. Use whatever your team will actually use.
The format doesn't matter. The act of documenting matters.
A decision log in a spreadsheet is infinitely better than a beautiful ADR template nobody fills out.
Making It Habit
Documentation has to be part of the workflow, not separate from it.
**Trigger:** Make a significant decision → **Action:** Document it immediately
Not later. Not in a documentation sprint. Now, while you're thinking about it.
Build the habit. Lower the friction. Make templates available. Praise documentation when it happens.
Teams that make this automatic have coherent systems and fast onboarding. Teams that don't have mystery systems and institutional amnesia.
The Compounding Effect
Documentation compounds.
Month one: You have decisions documented. Helpful but limited.
Month twelve: You have a year of decisions documented. New problems? Check if you've faced them before. New team members? Point them to the decision log. Debugging something weird? The decision record explains why it's that way.
The value grows over time. The earlier you start, the more value you accumulate.
Start today. Document the next decision you make.