Decisions You Don't Write Down Become Debt

Q: Decisions You Don't Write Down Become Debt

Architectural decisions you don't document become technical debt because code records only what a system does, not why it was built that way — and the rationale, trade-offs, and rejected alternatives can't be reconstructed from the code later. Capturing decisions as short, dated records (Architecture Decision Records) preserves the why.

"Francesco, you're writing the architecture. So the documentation — the decisions you make, the trade-offs you choose — is a deliverable. As important as the code itself."

My lead told me that in 2016. I never forgot it.

The assignment

It was my first assignment as a Technical Architect: design an application architecture from scratch for a large international retailer. Single-page applications for the web, plus hybrid builds for the devices their staff carried on the floor. I was an external consultant, I was the only one making the calls, and everyone around me came from the Java Enterprise world. Every choice was under scrutiny.

The hard decision

I made hard decisions. The one I defended the most: adopt a stable front-end technology, but wrap it in a layer — written specifically — so that the day a migration to the next major version became necessary, the path would already be open. Same for the build and deploy pipelines: I wrote them by hand for every target, web and hybrid alike.

None of that was the obvious choice at the time. The obvious choice was whatever the loudest framework debate of the month suggested. What made my choice defensible wasn't that it was clever — it was that I could explain why: the explicit trade-off between shipping something stable today and keeping the door open for tomorrow.

The sentence that changed everything

Then came that sentence from my lead. And I only understood what it really meant later.

Once the foundations were laid, I had to explain and defend every single choice in front of Italian and American stakeholders — people with different roles, different backgrounds, each interested in a different angle. I had to teach developers and DevOps on two continents how to use what I'd built. As an external consultant, with none of the informal authority that comes from being "one of us."

Without the decisions written down, it would have been impossible. Not the code — the code was there for anyone to read. The decisions. The reasoning behind each one. The alternatives I had considered and rejected, and why.

What I do now: lightweight decision records

That experience turned into a habit I bring to every team, and it's the first thing I push for: capture architectural decisions as they're made. Not a forty-page document nobody reads — a short, dated record for each significant decision:

the context and the problem;
the options on the table;
the choice, and the explicit trade-off it accepts;
whether it's a one-way door (hard to reverse) or a two-way door (cheap to change later).

The industry has a name for this — Architecture Decision Records (ADRs) — but the name matters less than the discipline. A plain markdown file in the repository, next to the code, is enough.

The lesson

Here is what fifteen years have taught me:

Decisions you don't write down become debt. Code tells you what the system does. Only written decisions tell you why — and the "why" is the one thing you can't reconstruct by reading the code. Six months later, the person asking "why did we do it this way?" is often you.

What was the sentence, or the moment, that changed how you work? I'm genuinely curious to read your turning points.