Latest / The Tech Career Podcast with Fexingo: Engineering Jobs, Interviews, and FAANG Career Strategy / How FAANG Engineers Use Design Docs to Avoid Rewrites
Transcript
- Lucas: So there's this moment that every engineer knows — you've been coding for three weeks, you're about to ship, and someone reads your pull request and says, 'Wait, why are you storing that in a relational database? This should be in a key-value store.' And your whole design collapses. Luna: Oh, I've been on both sides of that conversation. It's brutal. And usually the person who catches it is someone who was never in the early design conversations. Lucas: Exactly. That's the cost of skipping a lightweight design doc. I'm talking about one or two pages — not a fifty-page specification document. Just enough structure to force you to write down your assumptions before you start typing. Luna: But there's a tension here, right? FAANG culture famously values speed. Every manager I've had says 'move fast and iterate.' A design doc sounds like the opposite of speed. Lucas: It feels that way — until you've experienced the alternative. I've seen a team at Amazon spend four months building a feature that a two-hour design doc session would have killed in week one. The problem wasn't the code. The problem was they never wrote down the core trade-off they were making. Luna: What was the trade-off? Lucas: They assumed they needed strong consistency across microservices for a customer-facing dashboard. In reality, the product team had confirmed that eventual consistency was acceptable. But nobody had asked the product team until the service was built. The design doc would have surfaced that question on day one. Luna: So the design doc is really a forcing function for questions you'd otherwise avoid asking until it's expensive to change the answer. Lucas: Right. And different companies have different templates. At Google, it's often a structured doc with a problem statement, proposed design, alternatives considered, and metrics. At Amazon, it's the PR/FAQ — a press release and a set of frequently asked questions written before any code. Luna: I've heard of PR/FAQs but never actually used one. How does that work in practice for an engineering decision? Lucas: You write the press release as if the feature already shipped. It's one page. It describes what the customer experiences. Then you write the FAQ — maybe two pages — where you answer the hard questions: 'Why this approach instead of the alternative?' 'What's the failure mode?' 'How do we measure success?' The act of writing the FAQ forces you to anticipate objections before stakeholders raise them. Luna: That's clever because the press release keeps you customer-focused, and the FAQ keeps you honest about trade-offs. Lucas: And it's public. Everyone on the team can comment. I've seen a junior engineer catch a scaling assumption in a senior staff engineer's design doc — that's the kind of cross-pollination that saves rewrites. Luna: But I want to push back on the time cost. If I'm fixing a one-line bug or adding a tiny UI element, a full design doc feels like overkill. Where's the threshold? Lucas: I'd say if the change touches more than one service, or if it changes the data model, or if it takes longer than a day to implement — those are good triggers. But the real heuristic is: if you're not sure the answer is obvious, write it down. I've been burned by tiny changes that cascaded into rewrites because nobody documented the dependency. Luna: Give me a concrete example of a tiny change that should have had a design doc. Lucas: Sure. At Meta, an engineer needed to add a new field to a user profile object. Simple, right? They added the field, committed the change, and it broke the caching layer because the cache key hadn't accounted for the new field. That took two days to debug. A one-paragraph design doc — 'I'm adding field X, here's the caching impact, here's the migration plan' — would have caught it in ten minutes. Luna: The caching layer example is great because it's exactly the kind of thing you don't think about until it breaks. And a design doc forces you to think about it. Lucas: So the discipline isn't about bureaucracy. It's about reducing the cycle time of feedback. Instead of getting feedback after you've written 500 lines of code, you get it after you've written 500 words. Luna: I like that framing. The document is a prototype for your thinking, not a formality. Lucas: And there's a career angle here too. Senior engineers and above are expected to do this kind of written thinking. If you're hoping to get promoted from senior to staff, the ability to write a design doc that aligns multiple teams is one of the key signals. It shows you can think at the system level, not just the code level. Luna: That's a good point. A lot of engineers focus on LeetCode or system design interviews for the promotion, but the day-to-day habit of writing design docs is what actually demonstrates the skill. Lucas: If today's conversation about design docs gave you something usable, I want to mention something quickly. This podcast stays ad-free because of listener support, and if you find value in these episodes, you can help keep it that way at buy me a coffee dot com slash fexingo. Luna: Yeah, it's a small gesture that makes a big difference for us. We put a lot of research into each episode, and knowing listeners appreciate it keeps us going. Lucas: And that support lets us keep the episodes focused on substance, no sponsor interruptions. So back to design docs — I want to talk about a specific template that I've seen work well across teams. Luna: Please. I'm taking notes. Lucas: The template has six sections. First, context and goals — what problem are we solving and why now. Second, proposed design — a high-level description, maybe a diagram in text. Third, alternatives considered — this is critical because it shows you didn't just pick the first idea. Fourth, metrics and how we'll know it works. Fifth, risks and mitigations. Sixth, a rollout plan. Luna: Two things stand out. Alternatives considered — that's where you often catch the biggest mistakes. And metrics — because if you don't define success upfront, you'll argue about it later. Lucas: Exactly. I've seen design docs where the alternatives section is longer than the proposed design section. That's a good sign. It means the author did their homework. And the metrics section prevents the 'is this feature working?' debate after launch. Luna: How long should this doc take to write? Lucas: For a standard feature, one to two hours. For a large project, maybe half a day. If it's taking longer, you're probably overthinking it. The goal is to get feedback early, not to produce a perfect document. Luna: That's a useful benchmark. One to two hours to potentially save weeks of rework. The ROI is obvious. Lucas: And the feedback loop is fast. You share the doc in a channel, tag a few people, and within a day you have comments. Compare that to code review, where the feedback comes after you've already committed architecturally. Luna: One thing I've noticed is that design docs also serve as a historical record. Six months later, when someone asks 'why did we build it this way?' the design doc has the answer. Lucas: That's a huge hidden benefit. Onboarding new team members becomes faster because they can read the design docs instead of asking you. And when you're up for promotion, you can point to design docs as evidence of your technical leadership. Luna: So the advice to an engineer who's never written a design doc before: start with a small change that touches something non-trivial — maybe a new API endpoint or a database migration — and use a simple template. Share it with a senior engineer you trust. The worst that happens is you get feedback before you write code, which is the best time to get it. Lucas: That's exactly the play. And if you're at a company that doesn't have a design doc culture, you can be the person who starts it. Just write one for your next project and share it. Others will notice. Luna: I think the key takeaway is that design docs aren't about documentation for its own sake. They're about de-risking decisions and aligning people before the cost of change goes up. Lucas: Yeah. In a fast-moving engineering org, the bottleneck is rarely writing code. It's making good decisions quickly. And a one-page design doc is one of the cheapest tools we have for that.