You inherit a codebase. You find a strange design choice. You ask why it was built that way. Nobody knows. The person who made that decision left years ago, and their reasoning went with them. Sound familiar?
The Problem With Undocumented Decisions
Most engineering teams are reasonably good at documenting what exists. API documentation, architecture diagrams, README files. But almost no teams document why things are the way they are.
This creates a massive problem over time. When you do not know why a decision was made, you cannot know if it is still the right decision. You cannot know if changing it will break something. You end up either preserving decisions that no longer make sense or accidentally breaking things by changing decisions that were made for good reasons you do not understand.
"Code tells you what. Comments tell you how. Only humans can tell you why. And humans leave."
What is a Decision Log?
A decision log is simply a record of significant decisions, captured when they are made. Each entry includes:
- The decision. What was decided? Be specific.
- The context. What was the situation when this decision was made? What constraints existed?
- The options considered. What alternatives were evaluated?
- The rationale. Why was this option chosen over others?
- The consequences. What trade-offs were accepted? What follow-up work was created?
Why This Changes Everything
When decisions are logged:
- New team members onboard faster. They can understand why the system is the way it is without playing archaeology.
- Revisiting decisions becomes possible. When context changes, you can review the original reasoning and decide if the decision still holds.
- Arguments stop repeating. "We already evaluated that option in 2023, here is why we rejected it" ends circular debates.
- Knowledge survives turnover. When people leave, their reasoning stays.
What to Log
You cannot log every decision. Focus on:
- Technology choices (languages, frameworks, databases)
- Architectural decisions (service boundaries, data models)
- Process decisions (deployment strategies, testing approaches)
- Trade-offs (choosing simplicity over performance, or vice versa)
- Decisions not to do something (these are often the most valuable to record)
Keeping It Sustainable
The biggest risk with decision logs is that they become too burdensome and people stop using them. Keep it simple:
- Use a simple template. One page maximum.
- Store decisions close to the code they affect. In the repo is often best.
- Make writing decisions part of the normal workflow, not extra work.
- Review decisions during planning to ensure they are still valid.
Start Today
The best time to start a decision log was when your project began. The second best time is today. You do not need to retroactively document everything. Just start capturing decisions from now on.
Future you, and everyone who works on your codebase after you, will be grateful.