Latest / The Tech Career Podcast with Fexingo: Engineering Jobs, Interviews, and FAANG Career Strategy / How FAANG Engineers Write Design Docs That Get Approved
Transcript
- Lucas: You write a design doc at a FAANG company — and you might spend three weeks on it — only to have the review meeting turn into a debate about your choice of database driver. Luna: Oh, the bikeshedding trap. Everyone has a strong opinion about the color of the bike shed, not the bridge you're actually building. Lucas: Exactly. And the painful thing is, most engineers I've mentored write design docs that are technically correct but strategically wrong. They focus on the implementation details — the API signatures, the table schemas — and they bury the decisions that actually need sign-off. Luna: So what's the alternative? Because I've seen people swing the other way and write these vague, hand-wavy docs that get kicked back for being too high-level. Lucas: Right, you need a specific middle ground. Let me give you a concrete example. A friend of mine — senior engineer at Google — was leading a migration of a petabyte-scale data pipeline from a legacy batch system to Apache Beam. Classic infrastructure move. The first version of his design doc was forty pages. It had everything: data flow diagrams, error handling for every edge case, a detailed timeline. And it got absolutely shredded in review. Luna: Forty pages? That's a novel. What was the feedback? Lucas: The reviewers — three staff engineers and a tech lead manager — all said the same thing: 'I can't tell what you're actually proposing.' Because he'd buried the key trade-off — batch versus streaming semantics — on page twelve, in a subsection called 'Alternative Considered But Not Recommended.' Luna: Oh, the classic bury your tradeoffs move. I've seen that. It's like hiding the thesis of your paper in the footnotes. Lucas: Exactly. So he rewrote it. And the new structure is what I now recommend to every engineer I coach. It's three parts. Part one: a one-page executive summary that states, in five sentences, what you're doing, why, and the one big decision you're making. In his case: 'Migrate batch pipeline X to Beam. Rationale: reduce operational cost by forty percent and enable near real time processing. Decision: use exactly-once processing semantics with Apache Beam's Dataflow runner, accepting a two-second latency increase.' Luna: That's so clean. I can already see the reviewers nodding after reading that one page. Lucas: Right. Part two is where most engineers go wrong. It's not a detailed design — it's a list of exactly three trade-offs, each with a clear recommendation and the cost of the alternative. He listed: batch versus streaming, exactly-once versus at least once semantics, and in-house orchestration versus Cloud Composer. For each, he wrote one paragraph explaining the choice and one sentence on what you lose. Luna: So you're proactively framing the debate. Instead of letting reviewers invent their own favorite alternative, you say, 'Here are the three forks in the road. I picked this one. Argue with me if you want, but here's my reasoning.' Lucas: Exactly. And the magic is, the review meeting shrank from two hours to thirty minutes. Because nobody argued about the database driver — that was an implementation detail, not a trade-off. And the one time someone tried to bring up a fourth alternative — 'why not use Kafka Streams?' — my friend said, 'That's a valid alternative, but it's not in the top three trade-offs because it would require a complete rewrite of the ingestion layer. I can add it to the appendix for follow-up.' Luna: Beautiful. I love the appendix redirect. It's respectful but it keeps the meeting on track. Lucas: Part three is the actual design — but it's only three pages. API changes, data model, rollback plan, monitoring. No fluff. And here's the key: he wrote it last, after the trade-offs were settled. That way, if the trade-off section gets overturned — say the reviewers want at least once instead of exactly-once — he only rewrites one page of design, not the full forty. Luna: That's a great workflow insight. Don't write the detailed design until you've agreed on the big decisions. I've seen so many engineers do the opposite — they spend weeks on the detailed spec, then a reviewer says, 'Actually, I think we should use a different storage layer,' and the whole thing collapses. Lucas: And here's the thing — this structure works because it respects the reviewer's time. A staff engineer at a FAANG company might have to review three design docs in one afternoon. If yours is forty pages, they're going to skim it and maybe miss your critical assumption. But if yours is a clear one-page summary plus three trade-offs, they can engage deeply in twenty minutes. Luna: I want to talk about one specific anti-pattern I see a lot in design docs — the 'risk section' that's basically just 'risk: none.' Or they list risks but no mitigations. Lucas: Oh, that's a classic. I call it the 'risk section as cover your ass' move. You list 'potential data loss during migration' but then you write nothing about how you'll detect or recover from it. That's not a risk assessment — that's a confession. Luna: Right. The best design docs I've seen — they have a risk table. Column one: the risk. Column two: probability. Column three: impact. Column four: mitigation. Column five: what you'll do if the mitigation fails. And the senior reviewers love that because it shows you've thought about the failure modes. Lucas: Exactly. My friend's final doc — after the rewrite — had a risk table with five rows. The top row was 'Data duplication during the cutover window.' Probability: medium. Impact: high — because duplicates would inflate storage costs and skew analytics. Mitigation: idempotent writes on the sink. Rollback: replay the last hour from the source. And that one table probably saved him from three follow-up meetings. Luna: Let me ask you this — what about the political side? Because a design doc isn't just a technical document. It's a persuasion tool. You're trying to get buy-in from people who might have their own preferred solution. Lucas: Huge point. I've seen engineers write technically perfect design docs that get rejected because they didn't socialize the idea before the review meeting. You need to send the doc to key stakeholders — the team that owns the downstream system, the SRE team, the product manager — a week before the review. Ask them for early feedback. Address their concerns in the doc before they even raise them in the meeting. Luna: So by the time the meeting happens, you've already resolved the biggest objections. The meeting becomes a formality — or at least a discussion of minor details, not existential questions. Lucas: Exactly. And that's what separates a staff engineer from a senior engineer. The staff engineer knows that the design doc is fifty percent technical writing and fifty percent relationship management. You're not just documenting a solution — you're building consensus. Luna: I want to give our listeners one concrete takeaway they can use tomorrow. If you're writing a design doc right now, what's the first thing you should do? Lucas: Write the one-page executive summary first. Even if it's rough. Then send it to one trusted colleague — not your manager, not a reviewer — just a peer who will give you honest feedback. Ask them: 'Does this make sense? Is this the right trade-off?' If they can understand your proposal in five minutes, you're ready to write the full doc. If they're confused, rewrite the summary. Luna: That's solid. I'm going to start doing that myself. Lucas: And before we get too deep into the technical weeds, I want to mention something briefly. If today's conversation gave you something usable — a framework, a checklist, even just one sentence — and you've been thinking about supporting the show, a handful of listeners already chip in monthly at buy me a coffee dot com slash fexingo. That's literally what keeps this ad-free and focused on real engineering advice, not sponsored content. Luna: Yeah, it's a small group, but it makes a big difference. We're not asking for much — just that if you find value, you can throw in five bucks. No pressure. Lucas: Exactly. And now back to design docs — because I think there's one more anti-pattern I want to cover. The 'future work' section. Luna: Oh, the thing where people list everything they'd ever want to do, making the scope seem endless? Lucas: Right. 'Future work: real-time dashboards, machine learning on the data, multi-region replication.' And suddenly the reviewers think you're proposing a multi-year project. Keep future work to one sentence: 'After migration, we will explore real-time dashboards as a separate initiative.' That's it. Luna: I love that. Scope containment is a skill in itself. Lucas: So to sum up: one-page executive summary, three trade-offs with recommendations, a risk table, and a tightly scoped design section. Then socialize before the meeting. That's the recipe for a design doc that gets approved. Luna: And if you're a senior engineer listening, I'd challenge you to try this on your next design doc. It might feel uncomfortable at first — stripping away all the detail — but I think you'll find the reviews go faster and the decisions stick better. Lucas: Absolutely. Next episode, I want to talk about a related topic — how to handle the situation where your design doc gets rejected and you have to go back to the drawing board. There's a specific way to do that without losing credibility. Luna: That sounds like exactly the kind of thing we should cover. See you next time.