Latest / Tech Leadership with Fexingo: Engineering Managers, CTOs, and Technical Leadership Conversations / Why Your Team Needs a Technical Decision Record
Transcript
- Lucas: I've been thinking about a pattern I see a lot in engineering teams — especially fast-growing ones — where they make a big technical decision, six months pass, and nobody remembers why. So they end up revisiting the same debate, or worse, reversing a choice that was actually right for the context at the time. Luna: Right. We've talked about decision logs and RFCs on this show. But there's something more lightweight that a lot of teams skip — the Technical Decision Record. The TDR. Lucas: Exactly. And I think the reason it's underused is that it sounds bureaucratic. But a good TDR is maybe two paragraphs. It's not an essay. It's just enough to capture the context, the options considered, and the rationale behind the choice. Luna: So how is that different from an RFC, which we covered in episode 26? Or from an Architecture Decision Record, which is more formal? Lucas: Great question. An RFC is typically a proposal — something you write before a decision to gather feedback. An ADR is usually a more formal, structured document that lives in a repository. A TDR sits in between. It's written after the decision, but it's quick, informal, and focused on the 'why' rather than the technical spec. You don't need a template with twenty fields. Luna: What goes into a minimal TDR? Give me the skeleton. Lucas: Four things. Title — like 'Decision to migrate user profiles from PostgreSQL to DynamoDB.' Context — one or two sentences on the problem. Decision — what we chose. And consequences — what we expect to happen, both positive and negative. That's it. Luna: And where does it live? A wiki? A doc? A file in the repo? Lucas: I've seen all three. I personally prefer a Markdown file in the repo, next to the code. That way it's version-controlled, discoverable, and linked to the pull request where the decision was implemented. But the key is that it's easy to find later. If it's buried in a wiki that nobody reads, it's useless. Luna: Let me give you a concrete example from a CTO I talked to last month. Her team had a painful database migration about eighteen months ago — they moved their core transactional data from a monolithic MySQL instance to a sharded cluster. It took three months, had two rollbacks, and caused a six-hour outage. Lucas: Ouch. That's the kind of scar tissue that makes teams avoid database changes forever. Luna: Right. And a year later, a new engineer proposed moving that same data to a different database — CockroachDB — because they thought the sharding was causing consistency issues. But the original team had already considered CockroachDB and rejected it because of licensing costs and operational complexity. Lucas: That's exactly the kind of rework a TDR prevents. If that original decision had been written down — even two paragraphs — the new engineer could have read it in ten minutes and moved on to a higher-impact problem. Luna: Exactly. The CTO told me she now requires a TDR for any decision that takes more than a day to implement. It's a lightweight gate. Not to slow things down, but to capture knowledge. Lucas: I like that threshold — anything that takes more than a day. That covers most architecture decisions, library choices, infrastructure changes. And it doesn't apply to one-line bug fixes or config tweaks. Luna: The pushback I hear from engineering managers is, 'We don't have time to write docs. We're shipping features.' How do you respond to that? Lucas: I say, 'You don't have time to re-debate decisions six months from now.' A TDR takes maybe fifteen minutes. Re-litigating a choice that was already made can take days across multiple meetings. The math is clear. Luna: And there's a second-order benefit. When you write down the rationale, you surface assumptions. Sometimes you realize the decision is based on a hunch, not data. That can be uncomfortable, but it's useful. Lucas: Totally. I've had moments where I started writing a TDR and thought, 'Wait, we didn't actually evaluate that alternative properly.' It forces intellectual honesty. Luna: So let's talk about the format again. You said four parts. Is there a specific way to title them that makes them searchable? Lucas: I like a date prefix — like '2026-06-09-migrate user profiles to dynamodb.md'. That way they sort chronologically. And the filename should contain the key nouns so you can grep for it. 'DynamoDB' or 'user-profiles'. Luna: And do you link from the TDR to the relevant code or PR? Lucas: Absolutely. In the 'Decision' section, I include a link to the PR where the change was merged. And optionally a link to any RFC or design doc that preceded it. That creates a trail. Luna: One thing I've noticed is that teams often stop writing TDRs after a few months. It becomes a chore. How do you make it stick? Lucas: Make it part of the pull request checklist. Not as a blocker, but as a reminder. When a PR touches infrastructure or a new dependency, the reviewer asks, 'Is there a TDR for this?' Over time, it becomes cultural. Luna: Another trick from that CTO: she puts a TDR template in the repo — just a Markdown file with headings and placeholder text. The barrier to starting is even lower. Lucas: That's smart. And the template should be short. If it's more than ten lines, people will resist. Keep it to: Title, Context, Decision, Consequences. That's it. Luna: I want to zoom out a bit. We've talked about decision debt, RFCs, design docs. Where does the TDR fit in the broader ecosystem of engineering documentation? Lucas: I see it as the lightweight cousin of the ADR. ADRs are often more formal — they have a status, a date, an author, a supersedes field. TDRs skip the metadata. They're just a quick log. And they're less about architecture and more about any technical decision — library choice, tool adoption, process change. Luna: So if I'm a senior engineer or an engineering manager, what's the one thing I should do this week? Lucas: Pick the last non-trivial technical decision your team made. Write a two-paragraph TDR for it. Put it in your repository. Then tell your team you did it and ask them to do the same for the next decision. Start small. Luna: I like that. It's a habit, not a project. And honestly, if today's episode gave you one actionable idea — maybe that TDR template — and it felt worth a coffee to you, that's exactly the kind of signal that keeps this show ad-free and going. There's a link in the show notes: buy me a coffee dot com slash fexingo. Lucas: Exactly. And it truly is the smallest ask — if you got value, great. If not, the next episode will have something else. We're grateful either way. Luna: So back to the practical side — let's talk about what a TDR looks like in practice. I'll write a sample right now: 'Context: Our user profiles table in PostgreSQL has grown to 50 million rows and read latency is above 200 milliseconds for complex queries. We need a solution that scales reads horizontally.' Lucas: Perfect. Then 'Decision: Migrate user profiles to DynamoDB with a single-table design, keeping PostgreSQL for transactional order data. Rationale: DynamoDB offers predictable sub-10 millisecond latency at any scale, and our read-heavy workload fits the access pattern. We evaluated Cassandra and Spanner — Cassandra had higher operational overhead, Spanner had higher cost.' Luna: And then 'Consequences: Positive — faster reads, auto-scaling. Negative — we lose SQL joins, so we'll need to denormalize and handle eventual consistency. Trade-off accepted.' That's it. Lucas: That's a TDR. Fifteen minutes to write. Could save a future team weeks of investigation. And if someone later says, 'Why didn't we use Spanner?' there's a clear answer, not just tribal memory. Luna: One more thing: what about decisions that turn out wrong? Should you update the TDR? Lucas: Yes, but don't overwrite the original. Create a new TDR that says 'We reversed the migration from DynamoDB back to PostgreSQL because of X, Y, Z.' Then link the two. That way you have the full timeline. Luna: That's honest. And it builds a culture where mistakes are learning opportunities, not blame. Lucas: Exactly. And that's the deeper value of TDRs — they're not just documentation, they're a tool for organizational learning. Every TDR is a gift to your future self. Luna: Alright, I'm going to write one this afternoon. I challenge our listeners to do the same. Thanks, Lucas. Lucas: Thanks, Luna. See you next time.