Have you ever been maintaining an e-commerce store and stumbled upon a solution that just doesn’t make sense to you? It’s tempting to assume that whoever made that decision—whether it’s choosing a particular technology or taking a certain approach—simply didn’t know what they were doing. But let’s take a step back.
What led them to that choice? What constraints, knowledge, and resources did they have at the time? They couldn’t predict the future, but you, looking at the final result, have the advantage of hindsight. It’s easy to judge when you already know the outcome.
When working on an e-commerce project (or any IT-related project), you’re constantly making decisions—big and small. Each decision comes with its own context, whether it’s time constraints, project goals, or unexpected challenges. The truth is, there’s rarely a perfect choice, and there’s always the risk that today’s decision might turn into tomorrow’s headache.
Often, the biggest factor in choosing speed over quality is time. When a deadline is breathing down your neck, you focus on getting things done—the polishing comes later. In that moment, you’re making the best choices you can with the time you have. But fast forward a few months or years, and you look at that code and think, What was this person doing? Why didn’t they use a better approach?
And maybe you’ve been there—looking at your own code from a year or two ago, shaking your head, wondering, What was I thinking? This is all wrong. But here’s the thing: there is a way to understand what you were thinking back then. You need to document your decisions—or more specifically, the context behind them. Write down what you’re considering, the pros and cons of each option, and why you ultimately chose a particular solution. Don’t stop there—also note any limitations and important things other developers should be aware of when working with or integrating your solution.
Doing this doesn’t just create a history of your decisions—it helps you clarify your own thinking. Sometimes, by writing things down, you might even realize there’s a better approach than what you originally planned. This way, you can catch potential issues before you even write a single line of code, instead of spending hours only to realize the initial idea was flawed.
Documenting your decisions—especially the context and alternative solutions—isn’t just useful for future developers. It’s useful for you when you come back to maintain the project months or years later.
Architecture Decision Record
There’s a framework that can help you structure your decision notes: Architecture Decision Record (ADR). An ADR is a document that captures a single decision along with all its related context. All ADRs are stored in an Architecture Decision Log (ADL), which serves as a central place for tracking all project decisions.
You can store your ADL anywhere, but the best practice is to keep it as close to the code as possible—ideally, in the same repository as your project. There are also tools to help you generate and manage your Decision Log. One of them is a command-line tool called… ADR, which helps you create and maintain ADRs in a consistent format.
When it comes to structure, there are plenty of ADR templates available. You can choose one based on the specific context or project situation.
The default template used in the tool mentioned earlier—created by Michael Nygard—is a solid choice for general purposes. You can find more details in his blog post: Documenting Architecture Decisions.
This template includes:
- Context – A description of the environment in which the decision was made.
- Decision – The final choice documented in the ADR.
- Status – Whether the decision is accepted or not. This is useful for team discussions, as some decisions may not be approved right away.
- Consequences – Important information for everyone involved in the project. Think about potential issues or challenges that this decision might create.
If you want to explore other templates and tools, check out this repository: Architecture Decision Record. There are a lot of useful template that might fit ideally in you context. You can also make your own.
Which decisions should you document with an ADR? Pretty much any important one—or anything that could become a potential issue down the line.
Despite the name “Architecture” Decision Record, ADRs aren’t just for system or software architecture. You can use them for any decision that impacts the project, even something as simple as agreeing on a specific naming convention if there’s a debate within your team.
Keeping a clear record of your project decisions doesn’t just give you a history of what was decided—it also helps you make better decisions by forcing you to think through all possible solutions. Try ADR today, you will thank yourself later.
Be First to Comment