Latest / Tech Leadership with Fexingo: Engineering Managers, CTOs, and Technical Leadership Conversations / Why Your Engineering Team Needs a Decision Log
Transcript
- Lucas: So there's this practice I keep seeing in the best engineering teams that almost nobody talks about. It's not about code review, not about incident postmortems, not about OKRs. It's something they call a decision log. Luna: A decision log. Sounds dry. Like something a project manager would force on you. Lucas: It can be dry, and it can be bureaucratic. But done right, it's the single highest-leverage documentation practice I've encountered. Let me give you a concrete example. I worked with a fintech startup — about 40 engineers — that was migrating from a monolithic Ruby on Rails app to a microservices architecture on Kubernetes. They had this massive decision: how to handle inter-service communication. The team debated REST versus gRPC versus message queues for weeks. Luna: I can picture those meetings. A lot of opinions, very little memory of why the decision was made a month later. Lucas: Exactly. So their CTO started a decision log. It was just a shared Google Doc with a table: date, decision, alternatives considered, rationale, and the people involved. That's it. Every time they made a significant architectural choice, someone wrote a line. Six months into the migration, they had about forty entries. And then a new engineer joined, looked at the log, and within an hour understood why they chose gRPC over REST for internal calls — because of the streaming requirements for their real-time fraud detection pipeline. Luna: So the log replaced the need to track down the engineer who made the decision, who might have left the company by then. Lucas: Exactly. And it prevented re-litigation. Every few months, someone would propose switching to message queues for everything. They'd look at the log, see the rationale from the original decision — the latency requirements, the operational complexity — and realise that the trade-offs hadn't changed. The log saved them from repeating the same debates. Luna: That's huge. Even in small teams, I've seen decisions get made, then lost, then remade differently because nobody wrote down why the original path was chosen. Lucas: Yes. And that's actually the most expensive form of technical debt. It's not bad code — it's forgotten context. A decision log is like a git history for your thinking. And the beauty is, it scales from a two-person startup to a hundred-engineer org. Luna: I'm curious about the failure modes though. I've seen teams start one of these and it fizzles out after a month. What makes it stick? Lucas: The main failure mode is making it too formal too fast. You don't need a template with ten fields and an approval workflow. If it takes more than thirty seconds to log a decision, nobody will do it. Start with one line per decision. The second failure mode is not referring to it. The CTO in that fintech startup made a habit of opening the log in architecture reviews and saying, 'Let's check what we decided here six months ago.' That reinforced the habit. Luna: So the log becomes a living artifact, not a forgotten document. I like that. It's almost like a lightweight ADR — architecture decision record — without the ceremony. Lucas: Exactly. ADRs are a well-known pattern, but they can feel heavyweight. Decision logs are adr lite. You can always evolve them into full ADRs later if the team grows. The key is to start. Luna: And you mentioned that this is especially valuable during a platform migration. I'd think it's also useful for onboarding. When I joined my last team, I spent weeks trying to piece together why certain services existed. Lucas: Right. A decision log is the fastest way to bring a new hire up to speed on the architecture's rationale. It's like reading the footnotes of a history book. And it also helps with accountability — you can see who was involved in a decision, even if it was a group consensus. Luna: This kind of show — where we dig into practical practices that actually improve how teams work — this is exactly the kind of content we want to keep making. And we deliberately don't run ads on these episodes. If you want to support that choice, the link is buy me a coffee dot com slash fexingo. Lucas: Yeah. It's really listener support that keeps this ad-free and focused on what's useful. So if you've gotten value from today's conversation, that's the place. Luna: Alright, back to decision logs. You mentioned that the fintech startup's log saved them from re-litigating decisions. But what about when a decision needs to be revisited? How do you know when the log is holding you back? Lucas: Great question. The log should include a date, so you can see how old a decision is. If the assumptions have changed — say, your traffic grew tenfold, or a new technology emerged — then it's time to reconsider. The log gives you a starting point for that discussion. You don't blindly follow it; you use it as a baseline. Luna: So it's a tool for conscious decision-making, not a straitjacket. Lucas: Exactly. And one more thing: the log is also useful for post-incident analysis. When something breaks, you can check the decision log to see if the architecture choice contributed. That helps you separate systemic problems from one-off errors. Luna: I want to go back to the idea of alternatives considered. In that fintech example, they listed the alternatives and why they were rejected. That seems critical because it captures the trade-offs explicitly. Lucas: It's the most important column. Because if you only record the decision, someone later might think you didn't consider other options. The alternatives column shows you were deliberate. It also prevents the 'we should have done X' narrative that can poison team morale. Luna: So a decision log is as much about team culture as it is about documentation. Lucas: Absolutely. It signals that decisions are made thoughtfully, that debate is welcome, and that context will be preserved. That builds trust. And in remote or distributed teams, where you can't just tap someone on the shoulder, it's even more important. Luna: What about tools? Is Google Doc enough, or should teams use something like Notion or a wiki? Lucas: Start with whatever is already in your workflow. The fintech team used a Google Doc because everyone was already in Google Docs. The key is that it's searchable and accessible. If your team lives in Confluence, use that. If you use Notion, use that. The tool doesn't matter. The habit does. Luna: I've also seen teams use a simple markdown file in their repo, updated via pull request. That way, the decision log is version-controlled and tied to code changes. Lucas: That's a great pattern too, especially for engineering teams that are code-centric. It also makes it easy to review changes to the log. But the risk is that it becomes too heavy — you have to open a PR for every line. For quick decisions, a doc might be faster. Luna: So it's about finding the friction threshold. If the process adds friction, people won't do it. Lucas: Right. And that's why I recommend starting incredibly simple. A shared document. One line per decision. You can always iterate. The goal is to build the habit, not to create a perfect system. Luna: I'm thinking about the kinds of decisions that should go in the log. Not every pull request comment, but what threshold? Lucas: I'd say any decision that has a lasting impact on the architecture, the codebase, or the team's workflow. For example: choosing a database, deciding on a caching strategy, adopting a new framework, changing a deployment process. Also, decisions that were contentious or that had significant trade-offs. If the team debated it for more than thirty minutes, log it. Luna: That's a good rule of thumb. I also think decisions that are irreversible or very costly to reverse should definitely be logged. Lucas: Exactly. And the log helps with that too — you can look at past irreversible decisions and see if they actually paid off. It's a feedback loop for your decision-making process. Luna: So we've covered what it is, why it matters, how to start, and common pitfalls. If someone wants to implement this tomorrow, what's the one action they should take? Lucas: Create a document called 'Decision Log' in your team's shared drive. Add three columns: date, decision, rationale. At your next team meeting, ask everyone to log one decision they were part of in the last week. That's it. The first entry builds momentum. Luna: I love that it's a concrete, low-effort step. And it's one of those practices that pays dividends immediately — not just in saved rework, but in how the team thinks about decisions. Lucas: Yeah. The act of writing down why you chose something forces you to be clear about your reasoning. It makes you a better engineer and a better leader. And over time, the log becomes a map of your team's learning. Luna: Alright, I'm convinced. I'm going to start one this afternoon. Lucas: Do it. And let us know how it goes. We might do a follow-up episode in a few months with reader stories. Luna: That'd be great. For now, I think this is a solid starting point for any tech leader looking to reduce knowledge loss and make better decisions. Lucas: Absolutely. Thanks for the conversation, Luna.