# Write a design doc the client's engineers approve before you code > At a client site, a design flaw caught in a Google Doc costs far less than one found after the code is running. Here are seven steps to write that doc and get it through review. Original: https://fdetimes.net/en/guides/design-doc-client-review-before-coding/ Imagine you are an FDE who has just been sent to a client company. You are writing code inside someone else's system, their engineering team almost certainly has the final say, and one misunderstanding about scope can burn several weeks. At Google, design docs are written before coding and are described as "relatively informal" documents. Yet this loose kind of document is exactly where design problems get caught early, while fixing them is still cheap. A design doc is also a tool for reaching consensus on a design across an organisation. At a client site, it is how you agree with them before the first line of code is written. The guide below walks through seven steps applied to a hypothetical scenario. The result is a two- to three-page design doc you can send to the client's tech lead this week. ## What you will write, and what you need The hypothetical scenario: you have been sent to a logistics company to deploy an agent that reads support tickets and assigns category labels. The agent has to integrate with their internal ticketing system, and the client's platform team will be the approvers. You need three things: notes from your customer discovery sessions, a rough diagram of the client's current system, and an editor with margin comments, such as Google Docs. Nothing fancier is required. ## Step 1: Ask whether the solution is ambiguous Google's approach to design docs turns on one question: is the solution to the design problem ambiguous? If everyone already knows what to do, writing a doc adds little. Angela Zhang adds a rough benchmark: work likely to take one engineer-month or more should have a design doc. Treat that time mark as a secondary signal; ambiguity is still the deciding condition. In the example, the ambiguous question is whether the agent should write labels straight into the ticket database or go through a queue so the platform team keeps control. There are two reasonable options, and both affect the client's system. That is reason enough to write a doc. **Check:** you can state the core design question in exactly one sentence. If you cannot, you do not yet understand the problem and should go back to discovery. ## Step 2: Borrow an existing template and trim it The Pragmatic Engineer has collected public templates from Google, Uber, Stedi and Monzo, with the advice to take whichever parts suit you. Below is a stripped-down template for client-site work. It is a simplification, not any company's official template. ```markdown # [Project name] — Design Doc Author · Client reviewers · Feedback deadline · Status ## Current system (1 paragraph) ## Goals ## Non-goals ## Proposed design (diagram + data flow) ## Alternatives considered and trade-offs ## Open questions for the client ``` The "Feedback deadline" line and the "Open questions" section are additions specific to FDE work. The first gives the review a clear end date. The second turns what you do not yet know into tasks the client has to answer. ## Step 3: Non-goals are where you fix the scope In Google's definition, non-goals are things that could reasonably be goals but are deliberately excluded. "Could reasonably be" is the key phrase. Writing "will not rebuild the ticketing system" is useless, because nobody is asking for it. | Goals | Non-goals | |---|---| | The agent assigns category labels to new tickets | The agent replies to customers on its own | | The platform team can review every label | Relabelling all historical tickets | | Wrong labels can be corrected by hand | Changing how the customer support team works | In this scenario, all three non-goals on the right are things a client manager could well ask for halfway through the project. Writing them down at the start means you have settled the negotiation before any dispute arises. **Check:** show the non-goals list to someone outside the project. If they react with "wait, you're not doing this?" to at least one line, you have written it correctly. ## Step 4: Write the trade-offs, not just the answer According to descriptions of how Google works, a design doc focuses on high-level strategy and trade-offs. Angela Zhang writes that the main purpose of a design doc is to make you think the design through and gather feedback from others, not to serve as a record. In the example, put the two options side by side. Writing straight to the database is fast and has fewer components, but it gives the agent write access to the client's core data. Going through a queue is slower and adds one more thing to operate, but the platform team keeps control. You recommend one option and state why. The client's engineers live with that system every day, so they are likely to see risks you have missed. Writing out the trade-offs invites them to point those out, at exactly the moment when changes are still cheap. ## Step 5: One early reviewer first, the whole team later A post on the Refactoring English blog advises against sending a draft to everyone at once. Find one early reviewer first. At a client site, that person is ideally a colleague on your own team or a client engineer you have already worked with. The reason is practical. Every first draft has obvious holes. Letting the client's entire platform team see them wastes your first impression, when a single person is enough to catch them. ## Step 6: Send it, with a deadline The author of the Refactoring English post always gives reviewers at least two working days to read a design doc. Put that deadline at the top of the doc and in the message you send. For example: send it on Monday morning, with feedback due by the end of Wednesday. **Check:** your message states three things clearly: where the doc is, what you need them to decide, and when the deadline is. ## Step 7: Reply to every comment before closing it When comments start arriving, reply to each margin note and resolve a thread only when you are sure you have dealt with the point. Do not resolve threads just to make the doc look tidy. Commenters notice, and next time they may not bother giving feedback. For decisions that comments cannot settle, record them as a decision with a named owner. Stedi treats this kind of decision record as a mechanism that forces the parties to align on a decision that needs to be made. In the example, it is the evidence that the platform team agreed to the queue option. ## Why your doc gets ignored The most common mistake is writing a doc for work that is not ambiguous at all, so reviewers feel their time was wasted and skip your doc next time. The second is leaving out non-goals, or listing non-goals nobody was asking for. The third is sending a rough draft to the whole group without a feedback deadline, then waiting indefinitely for replies. **Key point:** A design doc at a client site is not a record. It is how the client's engineers say "no" early, while that refusal is still cheap. ## How this skill shows up on your CV When reading an FDE job description, look for phrases such as "work directly with customer engineering teams" or "drive technical alignment". That is where this skill gets tested. On your CV, do not write "strong communication skills". Write that you authored a design doc, and say who approved it and which decision it settled. If you have no real clients yet, practise at your current company: pick a task whose solution is still ambiguous, write a doc following the seven steps above and send it to another team for review. Another team inside the same company also sees your system from the outside, just as a client would. The best design doc is not the one that gets praised. It is the one the client's engineers corrected before you wrote a single line of code. **Try this week:** - Pick a task you are working on whose solution is still ambiguous and write a two-page design doc using the template above, with at least three non-goals - Send the draft to exactly one colleague as an early reviewer, and agree to review it together after two working days - Rewrite one line of your CV along these lines: wrote a design doc that the partner's engineering team approved before implementation ## Sources - [Design Docs at Google](https://www.industrialempathy.com/posts/design-docs-at-google/) - [How to Get Meaningful Feedback on Your Design Document](https://refactoringenglish.com/blog/useful-feedback-on-design-docs/) - [How to write a good software design document (Angela Zhang)](https://www.freecodecamp.org/news/how-to-write-a-good-software-design-document-66fcf019569c) - [Companies Using RFCs or Design Docs and Examples of These](https://blog.pragmaticengineer.com/rfcs-and-design-docs/)