The One Document That Gets Engineers Promoted

"The One Document That Gets Engineers Promoted"

Hey, welcome back. I'm Gaz, this is Gazar Breakpoint, and today I want to talk about the single most underused document in engineering. It takes about twenty minutes to write, almost nobody writes it, and it shows up in promotion packets more often than you'd expect.

Let me start with a story.

A team is building a new service. They need a database. Someone says "let's use NoSQL", everyone nods, and they ship. No write-up, no rationale, nothing. Just a decision made in a meeting that nobody recorded.

Eighteen months later, that lead has left the company. The product has changed. The access patterns are nothing like what they were on day one. And a new team is staring at this database going "why on earth did they pick this?"

Nobody knows. So they do the only thing they can do: they rewrite it. That rewrite costs around two hundred thousand dollars in engineering time.

And here's the part that really gets me. The original decision might have been completely correct for the context they were in. But because nobody wrote down the context, nobody could tell. The knowledge of why didn't leave with a bad decision. It left with a good one that just wasn't documented.

That's the problem I want to fix today. And the fix is the Architecture Decision Record, the ADR.

So here's the core idea. Decisions vanish, but consequences don't.

The consequences of your architecture stick around for years. The reasoning behind them evaporates the moment the meeting ends. People leave. Memories fade. Slack threads get buried. Six months later even the person who made the call can't reconstruct exactly why.

An ADR is just a small document that captures a single architectural decision at the moment you make it, while the context is still fresh. That's it. It's not a big design doc. It's not a process. It's one decision, written down, the day you make it.

Let me give you the structure, because it's genuinely simple. Every ADR needs three sections.

First: context. What's the situation? What forces are at play? What constraints are you working under? This is where you write down the things that are true right now: the team size, the scale you expect, the deadlines, the skills you have, the things you're uncertain about. This section is the one everyone skips, and it's the most valuable one. Because the context is what changes. And when the context changes, that's your signal to revisit the decision.

Second: the decision. What did you actually decide? State it plainly. "We will use X." Not "we're considering", not "we might". The decision. And ideally, the alternatives you considered and why you didn't pick them. Future-you wants to know what you already ruled out so they don't waste time re-litigating it.

Third: consequences. What becomes easier because of this decision? What becomes harder? What are you now committed to? What are you giving up? Good engineering is about trade-offs, and this section is where you're honest about the trade-off you just made. Both sides of it.

Context, decision, consequences. That's the whole document.

Let me make it concrete with an example. Say you're building a payments service, and you need to choose a database. DynamoDB or PostgreSQL.

The context: it's a payments service, so you need strong transactional guarantees. You need to move money atomically and you cannot tolerate partial writes. Your team already knows relational databases well. Your scale at launch is moderate, not planet-scale. And you have complex querying needs for reporting and reconciliation.

The decision: you choose PostgreSQL. You considered DynamoDB because it scales effortlessly and the ops burden is lower. But you ruled it out because the transactional model and the relational querying you need for reconciliation map much more naturally onto Postgres, and your team can move fast in it today.

The consequences: you get ACID transactions and rich querying out of the box, which is exactly what a payments domain wants. The cost is that you're taking on more responsibility for scaling later, and if you hit a point where you genuinely need horizontal scale beyond what a single Postgres can give you comfortably, you'll have work to do.

Now here's the section that separates senior work from staff-level thinking. The revisit condition.

You write down: we will revisit this decision if write throughput exceeds some specific number, or if we need multi-region active-active, or if the reporting load starts competing with transactional load. You name the condition that would make this decision wrong.

Most people write a decision as if it's permanent. It isn't. A staff-level engineer writes the decision and the exact circumstances under which it should be reopened. That's the difference between "we picked Postgres" and "we picked Postgres for these reasons, and here's the trigger that means it's time to think again." One is a statement. The other is a system for keeping the architecture honest over time.

Okay, so why does this end up in promotion packets? Three reasons.

Reason one: it makes your thinking visible. Promotion committees can't promote what they can't see. When you write clear ADRs, your reasoning becomes legible to people who weren't in the room. A senior engineer solves the problem. A staff engineer solves it in a way that the whole organisation can understand and build on. ADRs are proof of the second kind.

Reason two: faster onboarding and leverage across the team. When a new engineer joins and can read a trail of ADRs, they understand not just what the system is, but why it is that way. That's enormous. You've turned your individual reasoning into a team asset. That's leverage, and leverage is exactly what the staff and principal levels are measured on.

Reason three: decision-level impact. The thing that gets you promoted to staff is rarely the code you wrote. It's the decisions you influenced and the judgement you showed. An ADR is the durable artefact of judgement. It's the receipt. When someone asks "what's the scope of this person's impact?", a body of well-reasoned ADRs answers that question better than almost anything else you can point to.

One practical note before I wrap. Where you write these matters more than people think. I'm not a fan of burying ADRs in a wiki where they rot. I've talked before about writing high-level designs and ADRs in HTML or React rather than markdown, so they live closer to the system, stay current, and are actually pleasant to read. The format isn't the point today, but don't let a good ADR die in a forgotten Confluence page.

So, to wrap up. Decisions vanish, consequences don't. An ADR captures a single decision while the context is fresh: context, decision, consequences. Add a revisit condition and you've gone from documenting to engineering the decision over time. And do this consistently, and you build a body of visible judgement that is exactly what gets you promoted.

Pick one decision your team made recently with no write-up. Write the ADR for it this week. Twenty minutes. See how it feels.

That's episode 6. If your team uses ADRs, or if there's a decision you wish someone had written down, I'd genuinely love to hear it. You can find me on LinkedIn or through gazar.dev.

See you in the next one.