Latest / Tech Leadership with Fexingo: Engineering Managers, CTOs, and Technical Leadership Conversations / Why Good Engineers Need Technical Writing Skills
Transcript
- Lucas: If today's tech conversation gave you something usable, stick around — because I want to talk about a skill that separates good senior engineers from great ones, and it's not writing more code. Luna: Let me guess — writing about code? Lucas: Exactly. Technical writing. Not API docs — I mean design documents, RFCs, the kind of writing where you have to explain your architecture decisions in prose that another human being can follow. Luna: I've seen teams where the senior engineers actively avoid writing anything longer than a commit message. They think it's overhead. Lucas: Right. And that mindset is costing them. I was talking to the CTO of a company called Logix — about 150 engineers, Series B — and she told me about a policy she implemented two years ago. Any architecture change that touches more than one service requires a three-page written design document before any code is written. Luna: Three pages — that's specific. Did the engineers push back? Lucas: Oh, absolutely. The first month was brutal. Her best backend engineer — the guy who could build a microservice in a weekend — said it would slow him down. And she told him, 'That's the point. Slow down so we don't have to rewrite everything in six months.' Luna: I love that. So what happened after the first few months? Lucas: They started catching architectural issues in the doc phase that would have taken weeks to discover in code review. She said the number of critical bugs shipped dropped about 20 percent in the first year. Not because the engineers got better at coding — because they got better at thinking before coding. Luna: Twenty percent is huge. And it's not just bugs — I'd imagine it also reduces rework. When you write something down, you realize the gaps in your reasoning. Lucas: That's the mechanism exactly. Writing forces you to confront ambiguity. In code, you can hide behind complexity — a tangled if-else block that only you understand. But when you have to explain your approach in plain English to a peer, the cracks show. Luna: So how do you evaluate whether someone is a good technical writer? It's not about grammar or style. Lucas: No, it's about clarity of structure. Can they state the problem in one sentence? Can they list alternatives they considered and explain why they chose one? The CTO at Logix uses a rubric with three criteria: problem definition, alternatives considered, and risk assessment. If any of those sections is weak, the doc goes back for revision. Luna: I've seen teams that require design docs but they're treated as a formality — everyone writes them the day before the deadline. Lucas: Yeah, that's a culture problem. The doc should be written before any significant code is written. And it should be reviewed by at least two engineers who are not on the author's team. That cross-pollination is where you catch the really interesting blind spots. Luna: I want to ask about this in the context of promotion. When you're looking at a senior engineer for a staff or principal role, how much weight do you put on their writing? Lucas: A lot. Because at that level, your impact is through leverage — you're not writing all the code yourself. You're influencing architecture decisions across teams. If you can't communicate your reasoning in writing, you're limited to one-on-one conversations and that doesn't scale. Luna: Yeah, that makes sense. I've seen staff engineers who are brilliant in a room but their design docs are a mess — they assume too much context, they skip the background, and then nobody implements what they intended. Lucas: That's exactly the failure mode. And it's fixable. The best advice I've heard is to write the doc as if the reader has been on vacation for two weeks. You have to re-establish context, restate the constraints, and then walk through your decision tree. Luna: Let me zoom out a bit. There's a broader trend here — the industry is realizing that code is not the only output of an engineer. Communication is part of the job. Lucas: Absolutely. We've talked on this show about decision logs, about postmortems, about engineering ladders. Technical writing is the common thread. Every one of those artifacts requires written communication. Luna: And yet, most engineering teams don't train people on how to write. They train on new frameworks, new languages, but not on writing a clear RFC. Lucas: That's a gap a lot of CTOs are starting to address. Some companies have started doing 'writing workshops' — two-hour sessions where engineers practice writing a one-page design doc on a hypothetical problem and then get peer feedback. Luna: Have you seen any data on how that affects team performance? Lucas: There's a study from a large tech company — I think it was Google, but I've seen similar results at others — where teams that adopted a formal design doc process reduced the time from idea to production by about 15 percent. Because there were fewer mid-implementation surprises. Luna: That's counterintuitive — adding a writing step actually speeds things up overall. Lucas: Right, because the writing step front-loads the thinking. You avoid the classic pattern where someone codes for two weeks, then presents it and someone says 'but what about this edge case?' and you have to rewrite half the system. Luna: So if I'm a tech lead listening to this, what's one concrete thing I can do next week to start shifting my team's culture toward better writing? Lucas: Pick one upcoming feature — something medium-sized, not trivial but not a six-month project — and require a one-page design doc before any code is written. Give the author 48 hours to write it, then schedule a 30-minute review with three peers. Don't let the review turn into a code review; focus on the reasoning, not the syntax. Luna: And if the doc is bad? Lucas: Send it back. Say 'I can't evaluate this because the problem statement isn't clear. Please rewrite and we'll meet again.' That's uncomfortable the first time, but it sets a standard. And it's much kinder than letting someone build the wrong thing. Luna: I think that's one of those things that sounds harsh but is actually respectful — you're saying 'I believe you can do better and your time is too valuable to waste on a bad foundation.' Lucas: Exactly. And look, we talk about a lot of engineering practices on this show — and we're able to because listeners support the podcast directly. A small group of people chip in each month through buy me a coffee dot com slash fexingo, and that's what makes it possible to produce these episodes ad-free. So if you've been getting value from the show, that's the way to keep it going. Luna: Yeah, it's a pretty simple model — no sponsors, just listeners who find the content useful. And it keeps us independent. Lucas: Alright, back to the writing thread. One thing I didn't mention — the Logix CTO told me that after a year, the engineers who initially resisted the policy became its biggest advocates. Because they saw their own design docs being referenced months later by new hires who needed to understand the system. Luna: That's the long-term payoff. Documentation as institutional memory. Lucas: Right. Code tells you what the system does. A good design doc tells you why it does it that way. And that 'why' is what new engineers need most. Luna: So what about engineers who are strong writers but weaker coders — does this skill help them get promoted? Lucas: It can, but only if they also have the technical depth. Writing is a multiplier, not a substitute. You still need to be able to make sound architectural decisions. But if you can make those decisions and explain them clearly, you're far more valuable than someone who makes great decisions but can't articulate them. Luna: I think that's a good note to end on. Clarity in writing forces clarity in thinking. And that benefits the whole team. Lucas: Yeah. So next time you're about to start coding a complex feature, try writing the design doc first. You might be surprised what you discover.