The Y Files - explain decisions, not just code

The question I find myself asking more than any other is “Why?”…

• Why did we choose a custom CI/CD pipeline configuration instead of the standard one?
• Why is this a separate microservice instead of part of the core app?
• Why did we choose this weird database instead of something mainstream?
• Why are passwords hashed this way and not that?

Unfortunately, when the “why” behind decisions goes undocumented, it doesn’t just gracefully fade away—it comes back to haunt you.

By the time we get around to asking those questions, the people who knew the answers are often long gone, or maybe just have had too many nights of sleep since then. The result? They become unsolved mysteries. And whether it’s a new teammate or future-you, someone will be playing software detective without a clue or a motive.

So let’s talk about how to prevent every “why” from turning into a cold case.

🔗The truth is out there…write it down!

We need a way to capture the context of our decisions.

A decision without context, no matter how grounded in reasoning at the time, guarantees future confusion when context inevitably changes. Was it a performance trade-off? A legacy system constraint? A temporary workaround that became permanent? ¹ Knowing the answers to these questions usually leads to the question at hand: How can I safely make a change now that it’s been several weeks, months, or even years?

Without a trail of reasoning, it’s easy to second-guess decisions that may still be sound, repeat gotcha mistakes, or simply waste time and resources unraveling past logic.

Architectural Decision Records (or ADRs) bridge that gap.

These lightweight documents capture key decisions, along with their context, alternatives, and consequences. They give future readers (including future-you) a window into the context, constraints, and rationale that shaped the system. Think of them as diary entries, but with fewer feelings and more foresight. It’s a way of saying “We thought this through, and here’s how we got here.”

🔗I want to believe understand

If code is the what, ADRs are the why, and those two things belong together. Not every small decision needs an ADR—reserve them for documenting significant decisions that shape the structure, behavior, or direction of a software system. Storing your architectural decisions in source control means they evolve with your system, live alongside the code they affect, and are versioned just like everything else.

When writing an ADR, you don’t need to reinvent the wheel. Below are two templates based on what we use at Particular Software for smaller (yet still significant) and bigger decisions. We have gone through many iterations to arrive at what we feel works well, while keeping it simple, structured, and GitHub-friendly.

Here’s a very simple ADR template for small decisions:

# Description of architecture decision

## Context

<!-- Describe the problem/context and the reason(s) a decision needs to be made. -->

## Decision

<!-- State the decision with the rationale. -->

## Risks

<!-- Risks, how they are quantified, and how they might be mitigated. -->

## Alternative approaches considered

<!-- Alternative approaches considered and why they weren't chosen. -->

And now here’s a silly example using that template. This is clearly not an “architectural” decision, but we didn’t want to set the internet afire by doing something controversial like tabs versus spaces:

# Official company whiteboard marker color

## Context

Everyone is using different colored markers and they clash.
We need a uniform color to reduce color noise.

## Decision

Dark blue markers have been selected as the official color.

It is high contrast and easy to read. They're also available
at a steep discount from the local marker depot if we buy a
3 year supply.

## Risks

Some people really hate blue and might not read messages
written in them. We can mitigate this by introducing the
blue markers gradually.

## Alternative approaches considered

Red is too aggressive, yellow is too hard to read, and green
smells like moldy feet. Black would have been acceptable but
we would have to pay full price.

Bigger decisions need more to support. A richer ADR template can capture more context: underlying assumptions, the criteria used to pick between alternatives, impacted stakeholders and their needs, impacts on other areas of the business, and the consequences of not following the recommendation over time.

Here’s an example of an ADR for choosing the coffee source for the breakroom using that richer template. It had better get followed too, or remembering why we made decisions will be the least of our problems. :wink:

🔗Summary

Whether you use a predefined template or create your own, the key is the habit—make documenting architectural decisions part of your team’s routine. Architecture is full of trade-offs, and future-you deserves to know what led to them.

To learn more about ADRs, check out Microsoft’s Architecture decision record article and AWS’ ADR process.