Configuration is a hundred small decisions
An implementation is not one big choice. It's a hundred small ones: which warehouse logic, whose approval, what happens to a half-shipped order. Each feels obvious the day you make it. Three months later, nobody remembers why the system behaves the way it does — and someone is tempted to "fix" a setting that was deliberate.
A decision log is the boring habit that prevents that. One line per real choice: what we decided, and why.
What actually goes in it
- The decision: stated plainly, so it reads the same to everyone.
- The reason: the constraint or trade-off behind it, not just the outcome.
- The alternative we rejected: so no one relitigates it by accident later.
Why it earns its keep
New people onboard faster because the context is written down, not locked in one person's head. Changes get safer, because you can see which settings were deliberate and which were defaults. And when we hand a system over, you own the reasoning as well as the software — part of what "no lock-in" actually means.
Keep it small or it dies
A decision log fails the moment it becomes a document to maintain. Keep it to the choices that would confuse a smart newcomer. If a decision is obvious and will stay obvious, it doesn't belong there. The goal is a record you'll actually read, not an archive nobody opens.