Latest / The Tech Career Podcast with Fexingo: Engineering Jobs, Interviews, and FAANG Career Strategy / How FAANG Engineers Write Technical Design Docs That Get Approved
Transcript
- Lucas: You can write the cleanest code in the world — but if your technical design doc doesn't land, that code never ships. At least not without six months of back and forth. Luna: Yeah, and I think a lot of engineers underestimate how much a design doc is really a persuasion document. It's not just describing what you're building — it's convincing a room of busy people that your approach is the right one. Lucas: Exactly. And that's the skill that separates a senior engineer from a staff engineer. Anyone can write a spec. But can you write a one-page summary that a VP actually reads? That's the bar. Luna: So let's talk about the anatomy of a design doc that actually gets approved. What's the first thing you put in? Lucas: The one-paragraph summary. Not an abstract. Not an introduction. I mean a brutally concise summary that any engineer — even one who's not on your team — can read in thirty seconds and understand the problem, the proposed solution, and the key trade-off. Luna: I've seen people skip that section and just start with context and motivation. And then the reviewer is lost by paragraph three. Lucas: Right. And here's the thing: at Amazon, they call that the 'executive summary' in the narrative doc format. At Google, it's the 'TL;DR'. But the function is the same — it's the hook. If you don't hook them there, they're skimming the rest. Luna: What about the 'goals and non-goals' section? I feel like that's the part that causes the most review cycle friction. Lucas: That's because engineers love to argue about scope. A well-written non-goals section is a shield. You write, 'This design does NOT handle real-time streaming. That is explicitly out of scope for now.' And then someone comments, 'But what about real-time streaming?' And you just point to the non-goals section. Luna: It's a pre-emptive strike. I love it. Lucas: Exactly. Now, the next section that a lot of people get wrong is the 'alternatives considered' section. They treat it like a checkbox — list three alternatives, say why they're bad, done. But the real trick is to show genuine trade-off analysis. Luna: What do you mean by genuine? Like, don't just straw-man the alternatives? Lucas: Right. If you pick option A, you should be able to articulate the real cost of option B — even a cost that makes option B look good in some dimension. That builds trust. Reviewers can smell a biased comparison from a mile away. Luna: And what about the actual system design? Like, the diagrams and the API contracts. How detailed should that be? Lucas: Detailed enough that someone could implement it, but not so detailed that the doc becomes unreadable. I usually put the full API spec in an appendix. In the main body, I just show the key interfaces and the data flow. Use a sequence diagram if the interaction is complex. Luna: And the 'operations and rollout' section — I think that's the part that junior engineers skip, and then the SRE team blocks the launch. Lucas: Yes. If you don't explain how you're going to monitor this system, how you're going to roll it back, what the on-call impact is — you will get blocked. At Google, the SRE team literally has a seat at the design review table. They will veto your doc if the operations plan is weak. Luna: So let's talk about the review process itself. How do you handle a reviewer who clearly hasn't read the doc but is leaving comments anyway? Lucas: That's a classic. The best move is to schedule a synchronous review — a thirty-minute meeting where you walk through the doc slide by slide. You can't hide behind asynchronous comments if you're in the room. And if they still haven't read it, they'll say so in the meeting, and you can reschedule. Luna: Yeah, I've seen teams adopt a 'design doc office hours' model. One hour a week, anyone can bring their doc and get live feedback. It speeds things up a lot. Lucas: That's smart. And it creates a culture where writing docs is a shared practice, not a solitary chore. Now, one more thing — the 'controversial decisions' section. I don't see this in every template, but it's the secret weapon. Luna: What goes in there? The decisions you know will be unpopular? Lucas: Exactly. You pre-empt the debate. You write, 'We chose to use a single write master even though it's a single point of failure, because the consistency requirements outweigh availability in this case. We accept the risk.' That shows you've thought about it, and it defuses the argument before it starts. Luna: It also signals maturity. Like, you're not pretending your design is perfect. Lucas: Right. And that's the kind of signal that promotion committees look for. A design doc isn't just a technical artifact — it's a leadership artifact. It shows you can drive an outcome through collaboration. Luna: Speaking of driving outcomes — I know a lot of our listeners are preparing for staff engineer promotions right now. If they take one thing from this episode, what should it be? Lucas: Start your design doc with the one-paragraph summary. If you can't write that paragraph, you don't understand your own design well enough. And if you can write it, you're already ahead of most docs I review. Luna: That's a good litmus test. And if today's conversation gave you something useful, you can support the show at buy me a coffee dot com slash fexingo. It helps us keep the podcast ad-free and focused on real career advice. Lucas: Yeah, we really appreciate that. And honestly, every bit of support lets us spend more time digging into these topics instead of chasing sponsors. So thank you. Luna: Alright, back to the doc template. Lucas, you mentioned the appendix — what else belongs in there besides the full API spec? Lucas: I like to put a glossary of terms, especially if the design uses domain-specific language. Also, a changelog — so reviewers can see what's changed since the last version. That saves everyone time. Luna: And one last tip: use a consistent template across your team. At Amazon, they have the six-pager format. At Google, it's the design doc template. If your team doesn't have one, steal the best one you've seen and propose it as a standard. Lucas: That's a great way to leave a mark on your team's culture. And it's exactly the kind of thing that gets noticed at promotion time. So go forth and write docs that get approved.