17 ms·

Design Docs at Google

459 points by thesephist 6y ago

cramforce 6y ago
Author here. Let me know if you have questions or feedback.
- noselasd 6y ago
  Actual real design docs would be extremely helpful
- drewlander 6y ago
  I thought it was very helpful. I am sending it out to my manager and others on our team. We have gone through a transition where I work, and a new product owner likes to send us implementation manuals as design docs because that's how they did things many years ago. We have been trying to get them to work in our process, and I am hoping that this article will help reinforce a change in thinking or at least help us to come to an understanding. Thank you for writing it!
- 010101010101 6y ago
  This is great. At my company we normally create design docs, and I’ve seen each of the anti-patterns described here, along with their more informative/useful counterparts, but not seen a place that succinctly enumerates “do/don’t do” very well. A piece of feedback - I like to include sequence diagrams along side system diagrams to detail interactions a bit. I think this serves a similar purpose to documenting the API in an informal manner, and gives a good amount of information density (I _don’t_ expect everyone to read and digest all 5-15 pages of a document, pictures help people retain what’s important and also have a small thing to refer to in the future, IMO).
- fbunau 6y ago
  How do you get teams that have knowledge on a particular piece put in the work when it is not one of their goals / focusing on other things ?
  - cramforce 6y ago
    I know this isn't a satisfying answer, but tools like design docs or any $SoftwareDevelopmentMethodology do not help fix broken corporate governance. Concretely here, I'd try to make solving my problem the other team's goal. E.g. by inviting them to a summit during planning season and agree on common OKRs.
  - numbsafari 6y ago
    What really helps here is adopting a culture of shared ownership. If a team has knowledge, your best bet is to work with them to share it with you. But if they are too busy, or otherwise unwilling, then you will be forced to move ahead without them. You can't let teams like that become a bottleneck to progress. Similarly, if you are on a team that has important knowledge, it's really important to share that knowledge widely. Prepare lots of good resources to help spread that knowledge. Don't try to operate as gatekeepers or a cabal, instead, it's up to you to be an advocate and an activist for your knowledge. If you want other teams to respect your team's knowledge, then you need to make sure that they recognize that you have it, and that you are willing to share it. Lastly, it's best to adopt a strategy of empowerment, rather than ownership. Encourage and support consumers of your knowledge to help themselves, rather than requiring you to opine on every single question, or participate in every single design review. All of this, of course, takes leadership, because it's a cultural practice. Leadership has to invest in having teams document and share knowledge. Leadership has to reward and recognize knowledge sharers while similarly recognizing and working with knowledge hoarders to change their ways. Leadership has to identify when a team has become a blocker on progress and either add resources, or as noted above, encourage teams to work around them. "So and so is the networking expert but he won't help us fix this problem." "Okay, I'll work on getting his time, meanwhile let me find this outside consultant or I'll give you cover to do the work yourself since they are blocking." That last thing is your last resort, but you need to not be afraid to use it. I actually get the impression that Google suffers from that quite a bit (the existence of Principal Engineers who "squat" on problems is one I've seen discussed repeatedly by former employees, and something I've witnessed on OSS projects).
  - gowld 6y ago
    Pay people for producing value. If you believe design docs have value, pay people more for writing more better ones.
- streblo 6y ago
  My question is how do you avoid bikeshedding during this process?
  - lhorie 6y ago
    The alternatives considered section is a good place to deal with it. There you can enumerate all the arguments for and against any particular thing, so you don't end up talking in circles. Often times, the person writing the document has the most context/expertise and can provide a short explanation for why one option might be a better trade-off than another even though there are clear and logical arguments against it. Having data also helps. IMHO, a lot of bikeshedding is uneducated conjecture, which can be put to rest with proof-of-concepts, benchmarks, level headed comparison tables, discussion notes with others in the industry etc. At my company, large reaching technological decisions often involve meeting with people with relevant experience from FAANG/others to gather information.
- altgoogler 6y ago
  Hi Malte! Great article. I've agree that design docs are great part of what defines engineering culture at Google. I'd recommend to anybody who will listen that their company should do it also. Lots of people in this thread were burned by waterfall-esque requirements documents or formal specification, and I'd like to point out why I think design documents (at Google at least) are different and more effective than those things. I like to think of design docs as not an artifact produced by a project but as a communication mechanism of a team. You have an idea and you write down: * What are you trying to do? * Why are you doing to do it? * How are you going to do it? * What considerations have you made? Then you socialize it to one or two reviewers, who ask a lot of questions, then you take it to your team, who ask (relatively fewer) questions. The socialization part is key to the entire system. As you note: "The primary value that such reviews add is that they form an opportunity for the combined experience of the organization to be incorporated into a design. Most consistently, ensuring that designs take cross-cutting concerns such as observability, security and privacy into account is something that can be ensured in a review stage. The primary value of the review isn’t that issues get discovered per-se, but rather that this happens relatively early in the development lifecycle when it is still relatively cheap to make changes." If I printed out your article to show people, this is the part I would highlight in yellow. Contrast this with formal doc systems that rarely capture the "why" and "why nots". Future maintainers have a document that captures the thinking at the time, rather than trying to document the full implementation plan of a system. Hopefully this adds some context to those who've been burnt by more traditional approaches. edit: typos
cameronbrown 6y ago
Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints. I know this is fairly controversial, but our jobs isn't just to write code. Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it. Design docs are a way to get all of that out of the way _before_ writing thousands of lines of code. The review process nets significantly different feedback to code reviews too.
- Aperocky 6y ago
  > I know this is fairly controversial, but our jobs isn't just to write code. I don't know if this is actually controversial, but I would not want to work at a place where this is controversial.
  - eitally 6y ago
    I think -- from experience -- that in traditional IT organizations this is absolutely not true. The PMO is responsible for business requirements, and almost not time is invested in the creation of detailed DDs. You're essentially left trying to move from a PRD to writing code ... and if you have the luxury of an in-house SQA team and a relatively effective CI/CD process, you depend on quick feedback from stakeholders to certify whether the guesses and assumptions made by developers are correct or not. Since in many cases the business owner(s) had never actually considered many of the edge cases (stupid, basic example: previous company required CFO approval of all international travel requests. Tool was built with this logic. No one considered how to handle it when the CFO was unavailable for whatever reason, so the first time the CFO went on vacation it created all kinds of stupid chaos while a manual process was created.), flexible logic paths aren't designed into workflow apps. Similarly, for reporting/BI tools, there are frequently gaps between the answers executives want to glean from the data, and the business processes the ultimately result in the data creation. Because of this, nearly all reports are faulty, but unless you're close enough to the processes you don't have explainability and uninformed business decisions can result. Ditto from CRUD apps, where form validation rules can be insanely complex for stupid reasons, with the result being the data entered is impossible to use. Apologies for the diatribe. Big fan of design docs, but an even bigger fan of software engineering cultures that focus on simplicity and usability, rather than being everything to everyone (or worse, being a pet project of an exec who changes their mind every quarter about how things should work).
britbull 6y ago
> Are you unsure about the right software design, and would it make sense to spend upfront time to gain certainty? This is a great question to ask. It's human nature to lack foresight, especially when you are under pressure from deadlines, but in the long run it saves so much time.
WeNeedDemocracy 6y ago
At my place of work we probably wouldn’t follow this simply because we don’t love the design of Google’s products
time0ut 6y ago
Great article. I spend a lot of my time writing design docs these days. We derive a ton of value from it. The projects I work on are typically collaborations with several developers. It is important to all have the same vision for what we are building. A good design doc is a vehicle for a team to sync their mental models of the thing they are building. We also often have many other teams (security, infrastructure, operations, other business units, etc) who all have a stake in what we are doing. A good design doc helps build consensus with them. The review process gives them a voice in calling out concerns. It is much easier to solve a foundational problem before any code is written. One addition that isn't explicitly called out by the article, but I have found very valuable, is the inclusion of references. In my experience, good design docs typically include some references. Links to the docs for a piece of software we want to use, links to an AWS blog post explaining part of the architecture we want to use, links to academic papers explaining the algorithms we want to implement, etc. Good references support the design doc and help readers fill in knowledge gaps they may have.
- bigbizisverywyz 6y ago
  >It is much easier to solve a foundational problem before any code is written. This brings to mind the 1-10-100 rule. It takes 1 unit of effort to fix a problem in design It takes 10 units of effort to fix a problem during development. It takes 100 units of effort to fix a problem after going live.
ChrisMarshallNY 6y ago
I'm of a mind to reduce documentation as much as possible, or keep it as vague as possible. That's because I came from an environment that insisted on incredibly detailed, formal, approved-by-everyone-including-the-mens-room-attendant, documents. These became "concrete galoshes"[0] that turned what should have been an agile, iterative project into a waterfall behemoth that cost a mint, took forever to make, and delivered a result that no one wanted. I suspect that my current process[1] would not be acceptable for many organizations, as it basically requires that everyone involved be extremely experienced, and kept together as a team for years. I've actually come to realize that "tribal knowledge" is not the boogeyman that its made out to be; but is a way to get very high-quality, rapid, adaptive, development done. The main issue is that it does require good, empathetic management, long-term retention of experienced, capable people, and an "apprenticeship" model. These are not popular concepts in today's corporate world (at least, in the US). [0] https://medium.com/chrismarshallny/concrete-galoshes-a5798a55af2a https://medium.com/chrismarshallny/concrete-galoshes-a5798a5... [1] https://medium.com/chrismarshallny/forensic-design-documentation-54541925d30e https://medium.com/chrismarshallny/forensic-design-documenta...
- lhorie 6y ago
  I think something people need to be aware of is that the engineering culture at places like Google is extremely different than, say, a bank. Design docs work well for Google because it has decentralized, independent engineering teams composed mostly of reasonable people, with few or no mandates from outside their teams. They tend to fail at companies with underperforming, micro-managing, and/or overreaching teams (e.g. unionized project managers that have literally nothing to do, bizdev telling developers what features to implement (down to specifics), QA teams who are incentivized to find "flaws" ad-infinitum to look busy, etc). But I see this as a symptom of a fundamental dissonance in goals. Design documents are used by organizations whose goal is to build/change things. Many organizations are averse to change, and their processes reflect that, through overly microscopic documentation, convoluted approval chains, etc.
  - ChrisMarshallNY 6y ago
    Yeah, you are correct. But I have become rather cynical about the motivations of a lot of organizations, these days. Everyone seems to be promoting an environment where there's a constant circulation of relatively inexperienced (not always low-paid, but inexperienced) developers, staying at companies for short periods of time, then moving on. This requires a codified, ingrained structure that needs to be documented and supported. It applies to modern, "agile" companies, as much as it does to more traditional, "hidebound" corporations. People that come in need to be onboarded quickly, squeezed for every ounce of productivity possible, then let go, when they are no longer useful. This is supported by the employees, as much as by the managers. The salaries can be quite high; especially for people that are quick to adapt and come up to speed. But there is absolutely no substitute for an experienced, cohesive team that has developed a shared vocabulary and focus. I was fortunate to be a member of such a team. The person with the least seniority on the team had a decade. Everyone had over 30 years' experience in software development, and we got some fairly intense stuff done. Sadly, we were still subject to the kind of structure I mentioned above, and a lot of our product ended up being housed in substandard wrappers (we did "engine" code).
commandlinefan 6y ago
I like the idea of design documentation, but in 30 years of software development experience, I've never seen one done well. TFA does a reasonably good job of outlining what you'd want from an ideal design document but doesn't offer any advice on creating one that actually meets these criteria.
- colonelxc 6y ago
  One trick google uses is that there are 'standard' templates to start your design doc from. So it has all the sections mentioned in the post, and each section is initially filled with a description of what is needed there (and sometimes links to other supporting materials). Not everyone will be diligent and fill out all applicable sections, but it does help bring some uniformity to the process.
- AgloeDreams 6y ago
  Basecamp pitches and shaping are kinda like design docs but with a lot of what I found to be lacking here? You might want a look, they they refreshingly human-readable concepts.
- gowld 6y ago
  Same could be said for code, right? It's a great idea, but in 30 years we've never seen code done well. "Well" is a slippery word.
  - commandlinefan 6y ago
    But code actually works (eventually, usually). If you don't have code, you don't have software. If you don't have a design document... it's usually the same as if you do have a design document.
    - etse 6y ago
      In my experience, it’s not the same. Design docs allow a dialogue about the resulting code that code reviews are poorer at or less efficient at. Those conversations have saved us time and gives us confidence that the solution is the best for the problem.
mediocreguy 6y ago
Any good examplars of docs that use this format?
Slump 6y ago
Great article, generating consistent design docs that are both useful and not too time-consuming to create is something I am constantly working on. One thing I struggle with is finding examples of what others are doing in the industry. Does anyone have any resources they've found that provide examples of real-world design documents? Obviously each project is different but I'd be curious if others out there are publishing their templates/outlines of what they typically start with similar to this article. I feel like blog posts seem to serve this niche for a lot of open source projects but it would be interesting to see if anyone has found more structured examples.
PascLeRasc 6y ago
Does anyone know where to find real examples of design docs, possibly following this guide? I don't mean toy examples but something that's actually used by real people/orgs. My workplace has design docs but they're full of made-up words, so I'm pretty burned out by this kind of thing.
- Offpics 6y ago
  Deno design doc for example https://docs.google.com/document/u/0/d/1_WvwHl7BXUPmoiSeD8G83JmS8ypsTPqed4Btkqkn_-4/mobilebasic https://docs.google.com/document/u/0/d/1_WvwHl7BXUPmoiSeD8G8...
  - PascLeRasc 6y ago
    Thanks! That was interesting to read and gives me hope for a better workplace. So it's basically a much more thought-out Github issue/corresponding PR, would you agree?
- yegle 6y ago
  The author of Beancount (a text based accounting software) is a Googler and he recently shared https://docs.google.com/document/d/1qPdNXaz5zuDQ8M9uoZFyyFis7hA0G55BEfhWhrVBsfc/edit?usp=drivesdk https://docs.google.com/document/d/1qPdNXaz5zuDQ8M9uoZFyyFis... which is a pretty standard Google style design doc.
- vially 6y ago
  This is one I follow related to adding multi-window support to Flutter: https://flutter.dev/go/desktop-multi-window-support https://flutter.dev/go/desktop-multi-window-support I also found some of the chromium design docs quite interesting: https://www.chromium.org/developers/design-documents https://www.chromium.org/developers/design-documents
- cpeterso 6y ago
  Python's PEPs (Python Enhancement Proposals) are pretty good examples of design docs that describe the problem, proposed solution, and rationale: https://www.python.org/dev/peps/ https://www.python.org/dev/peps/
Areibman 6y ago
>Finally, the overhead of creating and reviewing a design doc may not be compatible with prototyping and rapid iteration. However, most software projects do have a set of actually known problems. Subscribing to agile methodologies is not an excuse for not taking the time to get solutions to actually known problems right. Here lies the biggest problem with the article. Most software projects _do not_ have a set of actually known problems. Agile exists precisely because it's hard to pin down what problems are, and you learn much more about your product with gradual experiments than with some grand, centralized design. Unless you are totally certain about your solution, design documents don't have a place for most projects.
- bdefore 6y ago
  While I agree, I find this common argument to have a faulty rhetorical approach. Leadership can often be allergic to allegations that there are problems that they don't know about. They can be outright defensive towards suspicions of uncertainty. I feel there may be a better way to express the utility of rapid iteration and design-as-you-go without triggering a fight response.
- theptip 6y ago
  I don't agree with this viewpoint. Agile is about just-in-time design, not no-design. At some point, you need to decide what the next increment you're going to build is. Before you write the code for that increment, you have by definition picked an actually known problem to solve, and for that you should write a design doc. I think what you're objecting to is the waterfall concept that you would write a design doc that covers the whole project, rather than just designing what you're going to work on next. I can wholeheartedly agree with that objection. However everything in the article is consistent with epic-level or story-level design. As the complexity and cost of change increase, more up-front design is appropriate. None of that is incompatible with the agile tenets of building small increments and delivering them often to make sure that they add value. If you're lucky enough to be working in the early stages of a project with a few thousand lines of code, and little to no production data on which to maintain integrity, then the value of formal design docs goes way down. But it's important to know that you'll need them later.
jhallenworld 6y ago
Design docs should be written in Markdown and stored in git. The advantage here is that the git hash can be used as a legal reference, for example in the case where a contractor is expected to implement the design.
- dilyevsky 6y ago
  I’ve tried this and I tried just gdocs like everyone at google did. Gdocs seems better for iterating because github review ui sucks (and everyone else sucks even more). If google critique was publicly available I’d much prefer markdown for designs
  - pmb 6y ago
    The best is to get agreement on the design is gdocs and then export it to Github so that the design and code live next to each other.
- bbeekley 6y ago
  We did this at a previous company in the healthcare space. It made audits easy since we could point to every instance of the design changing, who approved it, and the code that implements the change (all wrapped up in PR(s)). In general I like checking docs into source control, for all the reasons we use git and code reviews for the code itself.
nkingsy 6y ago
The emphasis on trade offs is the most important part for me, because it formalizes the search for alternative approaches. In the majority of my design docs, I end up swapping an “alternative” into the doc itself as I find myself more convinced by the alternative solution.
lowiqengineer 6y ago
I wonder why the "at Google" is necessary for the title. I'd be very surprised to see an organization not use some sort of design doc before building things - the only thing that would be different is the scale and scope of them. Of course, you won't see a "Design Docs at Amazon" on the front page of HN for...some reason. Gee, I wonder why?
- AnonC 6y ago
  > I'd be very surprised to see an organization not use some sort of design doc before building things - the only thing that would be different is the scale and scope of them. There are companies that use agile methodologies and eschew any kind of design documentation (they kneel at the altar of working code, and working code alone). I’ve seen teams just discuss things, get a few inputs and start writing (working) code and pass it through testing. The design process exists, but there’s no document or documents for anyone to refer to. There may be high level architectural documents, but not what many people understand as “design documents”.
  - sateesh 6y ago
    I always wonder how such an approach works towards building maintainable software whose scale is not trivial. Even assuming the code is reviewed unit tested, but still without some kind of design doc guiding the overall structure, and interactions wouldn't it lead to hard to maintain software ?
dgb23 6y ago
Related: https://www.joelonsoftware.com/2000/10/02/painless-functional-specifications-part-1-why-bother/ https://www.joelonsoftware.com/2000/10/02/painless-functiona... My opinion: If you don't specify things in a separate document in the form of text and pictures, then you end up doing it anyway but ad-hoc. Your "non-spec" now leaks into multiple tools and channels that likely don't talk to one another: emails, instant messages, file storage, notes, phone calls & discussions (AKA in your head/memory), Trello/Asana/Jira etc. and in peoples imaginations and expectations. A specification is just the things you do anyway but instead written down in a single maintained place. You can source control it and iteratively change it. All the parties can pull it and look at it before/during/after iterations and discussions. A spec doesn't need to be set in stone at all. It can grow/shrink/change iteratively with the thing you build. It can also define things that you specifically shouldn't do or worry about. A "design doc" seems to be something like that with a different name? Also a specification can help to communicate much more clearly, since you end up defining a vocabulary for processes, UI elements, technical components and so on. Tools I find useful to do this: - markdown + css + some tool to convert it to html/pdf - graphviz, especially for state-machines and decision trees, I prefer output as SVG rather than PNG. - UML diagrams or similar if applicable
- bigbizisverywyz 6y ago
  A really nice framework for specifying a system, I've found, is the vision document from RUP. It's great for putting the user front and center, and ensuring that you're building a system that people actually want and have a realistic business case.
- H8crilA 6y ago
  A design doc is not exactly a spec. It is a medium for discussion and a snapshot of what people thought at the time. They do get old pretty quickly and there's no expectation that anyone will update them (always put dates on such documents!). I think that specs should be checked into the codebase, either through some kind of code annotation, or next to it in text files, depending on what is it that you're doing.
  - 6y ago
eximius 6y ago
Half the time these are written after the fact (or updated after major changes), so they're often used as shitty documentation. I don't disagree with them, in principle, but I've yet to really see the benefit of them. The adage "In preparing for battle I have always found that plans are useless, but planning is indispensable" seems to apply.
the_arun 6y ago
Do we have any templates for design docs created by Google, Facebook, Twitter etc.,? Not to be negative - My problem is there is no spec/standard template for design docs (like someone compared it with Blueprints). If we have a template approved by industry leaders - it will be convenient. Otherwise everyone creates them in their own way - convenient for their use cases. But this will miss the consistency and all necessary ingredients. This ends up these docs fading out with time. Also, when design changes - these docs need to be updated. People don't do this. After a while, design docs become obsolete & overhead.
- thebrokencube 6y ago
  I think if there was a rigid spec, it would work against one of the points made early on in this doc (which I think is worth taking note of): > Rule #1 is: Write them in whatever form makes the most sense for the particular project. This is an unsatisfying rule, but I think it's important because each team/problem space/etc. is different and too strict of rules can often lead to documents that may end up being shallow. However this admittedly doesn't help with this other problem you brought up: > Also, when design changes - these docs need to be updated. ... but that may be okay given a shared understanding of what the goal of said document is. If the goal is to gain consensus around an implementation (as opposed to it being a living document), the document may have served its purpose by the time that consensus is reached, even if later on the design changes. If the goal is to have living documentation of a system, then maybe the rough format specified in this article isn't correct. One term I've heard for design documents is that they end up being a piece in a "Decision Log", which has helped me feel less bad if the document falls out of date. These documents end up being more point-in-time representations of the collective understanding/opinions of how a specific project/system was being thought of, and that has its own advantages even if it falls out of sync.
  - brown9-2 6y ago
    The first points here are absolutely correct. These documents are a way to communicate and get feedback (and iterate) on an idea with a group of people in your organization. Different organizations will communicate differently, and have different needs.
vngzs 6y ago
IMO the ideal format for conveying this information is to show, not tell. Give me an example document and annotate it with sidenotes that describe the purpose and importance of each section. Then we get to see how well it works, not leave it up to imagination.
whoevercares 6y ago
Frankly I think Amazon has a even heavier design culture. The designs for a new project (e.g to be launched at reinvent) could go as long as more than half year.
- koheripbal 6y ago
  Does duration really measure depth of design?
  - whoevercares 6y ago
    Yeah some are churns from reviewers, partner teams or even politics. The depth of the design are commonly pretty deep to the ground, because Amazon has many SDE1s with relatively low hiring bars and the design need to be super detailed for a safe execution
    - akhilcacharya 6y ago
      > SDE1s with relatively low hiring bars as an SDE1...yikes dude.
      - whoevercares 6y ago
        Sorry I mean compared to Google/FB... But that doesn’t translate to productivity though
        akhilcacharya 6y ago
        Again, that's a major yikes. I really don't think many others like me enjoy being called, er.., dumb.
cborenstein 6y ago
Design docs are great because writing them is aligned with the author's best interest, not just a future reader. (This is different from docs that are written after the project is complete). Design docs help you understand the project, identify dependencies, and avoid repeating work. Then they leave a trail for future engineers of the thought process that went into the code.
jeffbee 6y ago
A fun activity if you’re a Googler is to go read ancient design docs, like the original pitch for bigtable. They are pretty short for the most part, and they were written by the legends. These are the Federalist Papers of your company, they give real context to how the company arrived here. In particular I always enjoyed reading the jarring parts were they describe something that definitely did not make it into the implementation, or got removed later. It’s interesting to think about why they considered those things important enough to write down at the time. Now that I wrote the above, it's a bit sad that there aren't many design docs for open source software, even ones that originated from companies with good design doc culture. Where's a doc that discusses alternatives considered and rejected for kubernetes or grpc?
- spelunker 6y ago
  Great advice, jeffbee! hey wait a minute.
- jbeda 6y ago
  I wrote a design doc/PRD for k8s that outlined the basic API, distributed structure and why/how it related to open source and the marketplace. I lost it when I left google. It was a google doc IIRC and wasn't checked into source control.
  - robk 6y ago
    Someone must have shared access to find it for you though?
- mleonhard 6y ago
  Those "legends" joined the company very early and had opportunities that don't exist today. Why idolize them? Some of them are not good people. There are plenty of people who would do legendary things if the company let them.
Ozzie_osman 6y ago
Honestly I sometimes write a design doc even if no one else will read it. It can be as short as a few sentences, if needed. The main benefit is it forces you to: 1. Think strategically, not tactically, about what you're about to build. Beyond just "I need to get this working now". 2. It makes sure you can describe what you're about to do in plain English (or plain English plus some diagrams). If you're struggling to do that it's probably a sign you need to rethink your approach. Obviously, the organizational benefits described in the link are really important, too, but if all you've done is just 1 and 2 above that's already worth your effort.
petejames 6y ago
Writing helps you think. In the process of creating a design doc you get clarity of thought and refinements happen.
jkaptur 6y ago
It's important draw a distinction between a "design doc" and "documentation". tl;dr: "ought" vs "is". A "design doc", as described in the article, is a tool to help make a decision. It's a proposal. It is "ought". It describes the state of the world at a point in time, the desired change, and how to make it. Once the decision is made and the work is begun, it's rarely updated. "Documentation" is just the state of the world (generally "now" or "at release x.y"). It describes the design and use of the system, but has very little digression into ways it could be different. If it links to a design doc, it should be for Once you draw this distinction, it's clear that design docs should be in something like Google Docs, while documentation should be in something like a wiki or git. It's clear why it's fine for a design doc to be out of date, but it's a big problem if documentation is. etc.
jp42 6y ago
After reading this article I can relate it event trace (Chrome tracing) design doc form google, very succinct to the point: https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview# https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQt...!
- jeffbee 6y ago
  That is not a design doc, that is a format specification. It jumps directly to the implementation details without discussing the motivation. The reader has no way to evaluate the utility of the example JSON because the doc has not stated any use cases.
  - cmrdporcupine 6y ago
    And frankly that's how most of the design docs at Google really are. They're post-facto descriptions put together for the purpose of gaining promotion.
    - jeffbee 6y ago
      Yes and the way you can tell is the doc title is "FooBar Design Doc" but the shortlink is "foobarforperf".
juanbyrge 6y ago
It's a little ironic that the author of that post created AMP...
gregdoesit 6y ago
“Unstructured text, like in the form of a design doc, may be the better tool for solving problems early in a project lifecycle, as it may be more concise and easier to comprehend, and communicates the problems and solutions at a higher level than code.“ I could not agree more. I came across the concept of design docs consistently used for all projects at Uber. They were called RFCs here and they were introduced very early on. I wrote in more detail about my experience using these and how I am pretty sure they helped scale the engineering culture [1]. The most surprising thing I’ve observed is how sending these design docs out to all of engineering worked really well, until the org was over a thousand engineers. [1] https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/ https://blog.pragmaticengineer.com/scaling-engineering-teams...
wsetchell 6y ago
The article does not point out how the system can go astray. Design docs are great when they can in 1-2 pages describe a how an important/large/complex system will work and the tradeoffs made when designing it. Some groups in Google confuse design docs conflated with the promotion process, and thus engineers start create long/time consuming docs for every little thing as part of building a case for promotion.
blargmaster33 6y ago
Properly done MIL-STD-498 is a joy to behold. Operational Concept Description (OCD) - Used to sync with the marketing/sales non technical people. System/Subsystem Specification (SSS) - Software/System architect and agile team leads sync here System/Subsystem Design Description (SSDD) - Developers documents a rough outline of how stuff was done.
bruckie 6y ago
I find design docs really useful, even if no one else reads them, because they force me to clarify my thinking before I start the (more expensive) process of implementation. However, I've also noticed a couple of very common problems with design docs: - Many design docs don't clearly state the problem that the design is intended to solve. Often the best response to a design is "that problem isn't important to solve", or "there's another system that already solves this problem", or "there's a totally different approach that you should consider", but without a clear statement of the problem and why it's important to solve, it's hard to determine those kinds of things. - People often focus too much on the details of a design, vs. the important decisions that need(ed) to be made, the alternatives and rationale for those decisions, and the assumptions that they were based on. In a year, you probably won't care that much about the details of the parameters of some API, but you probably will care a lot about why you chose that API over some other one, and it's useful to have a record of that decision. It's useful to view a design doc as a distillation of the thought process behind a system, vs. a high-level description of how to build something.
justicezyx 6y ago
Hah, design docs at Google... I read probably hundreds of deigns docs during my 6 years at Google. I think among them, only a handful of design docs, like < 10, are considered clear, clean, and succinct. And all of them are more or less retrospective ones summarizing a system after it's already being implemented and running for a while. The newer design docs, which are served as actual working documents for an active projects, are no doubt primarily a process mechanism to solicit design inputs, and garner supports from stakeholders. It is a formality to show that the project owner is willing to waste his time and to convince so-called "reviewers" about the validity of the project. The reviewers usually do not read the design doc in earnest. Only the stakeholders, like the TL of the team, potential customers, partners, would spend serious time on them. It's more or less a debate ground for stakeholders to pointing fingers at the design process. That's also why the design doc is written in Google Doc in the first place. Once a design is "approved", it usually means from most major share holders are satisfied, to everyone is wearied down enough and the project has enough importance to actually push forward, they are OKed for implementation. After that the design doc is largely useless, the designs laid out in the doc is usually 1) too simple that there is no need to consult design doc anyway, one can explain it in a few minutes chat; 2) too complicated that the design diverges from the actual code that the design doc offers little guidance. And very few design docs sit in between. All in all, anything produced during a software engineering project seems all is about being a tool for organizing the human interaction process, the artifact, aside from a very high-level motivational piece, and the end result code + docs, whatever in between seems largely bears little value after the work is done.
choppaface 6y ago
It would be great to see some actual design docs in a blog post versus a summary article with zero primary references. (A postmortem of some design docs would be incredible!). One of the hardest things about introducing a design doc process to a team of engineers is providing concrete examples as seeds and ensuring feedback to make the process actually work. It can be really jarring to introduce the design doc philosophy to a larger team if all they've been doing is Scrum every week. Moreover, typically design docs happen at a quarterly rhythm and feedback periods can take weeks-- this slow cycle is a major impediment to consensus and learning. All this calls for material that speaks to differentiated learning. Extolling "we do this at Google" is a leaf in the wind.
- floil 6y ago
  Here you go: https://www.chromium.org/developers/design-documents https://www.chromium.org/developers/design-documents
staplung 6y ago
I worked at Google for 4 years. One thing that has always surprised me about documentation at Google is that they use Google Docs (just like everyone else) but have never seemed interested in making it less of a terrible tool for the task. It's relentlessly print oriented, which makes almost no sense these days (when was the last time you printed out a Google doc?), has no affordances for dealing with pre-formatted text (e.g. code), has basically no support for mathematical formulas, etc. In fact its actually evolved to be less suited to the task of technical documentation since it began given that earlier versions at least allowed you to define your own paragraph styles. I was hoping that Google Colab might evolve into a better/more general tool for writing tech specs but it doesn't seem to be moving in that direction really.
- maxwellg 6y ago
  Comment discovery is also horribly broken. So often, conversations _about_ a document contain information that don't necessarily _belong in_ the document, but still have value for future readers. Resolving comments makes it much harder to find them.
- xnx 6y ago
  Exactly correct about the print-oriented interface. Writely, and earlier versions of Google Docs didn't force you to pretend you were writing on a piece of paper. I would love a "Google Docs for text files"!
- akhilcacharya 6y ago
  At my company we use the internal Wikis or Quip for this. Versioned and effectively markdown formatted with builtin live charts or spreadsheets, respectively.
  - galkk 6y ago
    Amazon had both wiki and Quip, and both were bad, but differently. Wiki was painfully slow to edit (and render, ~2 sec page render was typical, and I'm not counting some graphs that were asynchronously rendered). Quip is good for fast editing, but anything that needed code formatting there is bad. It's even more "print oriented" than Google docs. Fixed page width, very fixed formatting, tables are awful.
rckoepke 6y ago
I'd love some examples of real-world design docs.
- mbakke 6y ago
  The Ganeti virtualization toolkit which was developed internally at Google and released as free software is full of such design docs. I always enjoyed reading those as an external Ganeti user: http://docs.ganeti.org/ganeti/master/html/#implemented-designs http://docs.ganeti.org/ganeti/master/html/#implemented-desig...
kcudrevelc 6y ago
I've worked at Google for a while, and a few years ago I wanted to release an open-source project. Since the code was going on Git, it made sense to throw the design there too, so I just added a DESIGN.md to the top-level of the project. This has had a remarkably nice effect: sometimes, when people make large changes to the project, they update the design to reflect the changes! See this lovely commit as an example: https://github.com/google/stenographer/commit/d678531a3e5a87b321e9247ba60d0019768681de#diff-6a735bf86dcc8fb712e11c207df01ae4 https://github.com/google/stenographer/commit/d678531a3e5a87...
maps7 6y ago
This is awesome! Thanks for posting - I think I can use this where I work. I am wondering though.. how do you allocate time to work on the design doc? I'm sure sometimes it takes a day but other times it can take longer and if there's a review needed then it would take even longer. I work in a agile/scrum team - how would this work fit in there?
winrid 6y ago
At a medium sized company/startup that follows this pattern. It works really well. Much better than the core platform team just going and changing a bunch of stuff every release with no documentation, which I've experienced consistently at my last job.
blululu 6y ago
This is a very optimistic presentation of design docs. The flip side is that these documents can become a touchstone for bike shedding or and excuse to make slideware in lieu of software. A lot of administrative bloat can creep in through design docs.

459 points by thesephist 6y ago

cramforce 6y ago

Author here. Let me know if you have questions or feedback.

noselasd 6y ago
Actual real design docs would be extremely helpful
drewlander 6y ago
I thought it was very helpful. I am sending it out to my manager and others on our team. We have gone through a transition where I work, and a new product owner likes to send us implementation manuals as design docs because that's how they did things many years ago. We have been trying to get them to work in our process, and I am hoping that this article will help reinforce a change in thinking or at least help us to come to an understanding. Thank you for writing it!
010101010101 6y ago
This is great. At my company we normally create design docs, and I’ve seen each of the anti-patterns described here, along with their more informative/useful counterparts, but not seen a place that succinctly enumerates “do/don’t do” very well. A piece of feedback - I like to include sequence diagrams along side system diagrams to detail interactions a bit. I think this serves a similar purpose to documenting the API in an informal manner, and gives a good amount of information density (I _don’t_ expect everyone to read and digest all 5-15 pages of a document, pictures help people retain what’s important and also have a small thing to refer to in the future, IMO).
fbunau 6y ago
How do you get teams that have knowledge on a particular piece put in the work when it is not one of their goals / focusing on other things ?
- cramforce 6y ago
  I know this isn't a satisfying answer, but tools like design docs or any $SoftwareDevelopmentMethodology do not help fix broken corporate governance. Concretely here, I'd try to make solving my problem the other team's goal. E.g. by inviting them to a summit during planning season and agree on common OKRs.
- numbsafari 6y ago
  What really helps here is adopting a culture of shared ownership. If a team has knowledge, your best bet is to work with them to share it with you. But if they are too busy, or otherwise unwilling, then you will be forced to move ahead without them. You can't let teams like that become a bottleneck to progress. Similarly, if you are on a team that has important knowledge, it's really important to share that knowledge widely. Prepare lots of good resources to help spread that knowledge. Don't try to operate as gatekeepers or a cabal, instead, it's up to you to be an advocate and an activist for your knowledge. If you want other teams to respect your team's knowledge, then you need to make sure that they recognize that you have it, and that you are willing to share it. Lastly, it's best to adopt a strategy of empowerment, rather than ownership. Encourage and support consumers of your knowledge to help themselves, rather than requiring you to opine on every single question, or participate in every single design review. All of this, of course, takes leadership, because it's a cultural practice. Leadership has to invest in having teams document and share knowledge. Leadership has to reward and recognize knowledge sharers while similarly recognizing and working with knowledge hoarders to change their ways. Leadership has to identify when a team has become a blocker on progress and either add resources, or as noted above, encourage teams to work around them. "So and so is the networking expert but he won't help us fix this problem." "Okay, I'll work on getting his time, meanwhile let me find this outside consultant or I'll give you cover to do the work yourself since they are blocking." That last thing is your last resort, but you need to not be afraid to use it. I actually get the impression that Google suffers from that quite a bit (the existence of Principal Engineers who "squat" on problems is one I've seen discussed repeatedly by former employees, and something I've witnessed on OSS projects).
- gowld 6y ago
  Pay people for producing value. If you believe design docs have value, pay people more for writing more better ones.
streblo 6y ago
My question is how do you avoid bikeshedding during this process?
- lhorie 6y ago
  The alternatives considered section is a good place to deal with it. There you can enumerate all the arguments for and against any particular thing, so you don't end up talking in circles. Often times, the person writing the document has the most context/expertise and can provide a short explanation for why one option might be a better trade-off than another even though there are clear and logical arguments against it. Having data also helps. IMHO, a lot of bikeshedding is uneducated conjecture, which can be put to rest with proof-of-concepts, benchmarks, level headed comparison tables, discussion notes with others in the industry etc. At my company, large reaching technological decisions often involve meeting with people with relevant experience from FAANG/others to gather information.
altgoogler 6y ago
Hi Malte! Great article. I've agree that design docs are great part of what defines engineering culture at Google. I'd recommend to anybody who will listen that their company should do it also. Lots of people in this thread were burned by waterfall-esque requirements documents or formal specification, and I'd like to point out why I think design documents (at Google at least) are different and more effective than those things. I like to think of design docs as not an artifact produced by a project but as a communication mechanism of a team. You have an idea and you write down: * What are you trying to do? * Why are you doing to do it? * How are you going to do it? * What considerations have you made? Then you socialize it to one or two reviewers, who ask a lot of questions, then you take it to your team, who ask (relatively fewer) questions. The socialization part is key to the entire system. As you note: "The primary value that such reviews add is that they form an opportunity for the combined experience of the organization to be incorporated into a design. Most consistently, ensuring that designs take cross-cutting concerns such as observability, security and privacy into account is something that can be ensured in a review stage. The primary value of the review isn’t that issues get discovered per-se, but rather that this happens relatively early in the development lifecycle when it is still relatively cheap to make changes." If I printed out your article to show people, this is the part I would highlight in yellow. Contrast this with formal doc systems that rarely capture the "why" and "why nots". Future maintainers have a document that captures the thinking at the time, rather than trying to document the full implementation plan of a system. Hopefully this adds some context to those who've been burnt by more traditional approaches. edit: typos

cameronbrown 6y ago

Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints. I know this is fairly controversial, but our jobs isn't just to write code. Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it. Design docs are a way to get all of that out of the way _before_ writing thousands of lines of code. The review process nets significantly different feedback to code reviews too.

Aperocky 6y ago
> I know this is fairly controversial, but our jobs isn't just to write code. I don't know if this is actually controversial, but I would not want to work at a place where this is controversial.
- eitally 6y ago
  I think -- from experience -- that in traditional IT organizations this is absolutely not true. The PMO is responsible for business requirements, and almost not time is invested in the creation of detailed DDs. You're essentially left trying to move from a PRD to writing code ... and if you have the luxury of an in-house SQA team and a relatively effective CI/CD process, you depend on quick feedback from stakeholders to certify whether the guesses and assumptions made by developers are correct or not. Since in many cases the business owner(s) had never actually considered many of the edge cases (stupid, basic example: previous company required CFO approval of all international travel requests. Tool was built with this logic. No one considered how to handle it when the CFO was unavailable for whatever reason, so the first time the CFO went on vacation it created all kinds of stupid chaos while a manual process was created.), flexible logic paths aren't designed into workflow apps. Similarly, for reporting/BI tools, there are frequently gaps between the answers executives want to glean from the data, and the business processes the ultimately result in the data creation. Because of this, nearly all reports are faulty, but unless you're close enough to the processes you don't have explainability and uninformed business decisions can result. Ditto from CRUD apps, where form validation rules can be insanely complex for stupid reasons, with the result being the data entered is impossible to use. Apologies for the diatribe. Big fan of design docs, but an even bigger fan of software engineering cultures that focus on simplicity and usability, rather than being everything to everyone (or worse, being a pet project of an exec who changes their mind every quarter about how things should work).

britbull 6y ago

> Are you unsure about the right software design, and would it make sense to spend upfront time to gain certainty? This is a great question to ask. It's human nature to lack foresight, especially when you are under pressure from deadlines, but in the long run it saves so much time.

WeNeedDemocracy 6y ago

At my place of work we probably wouldn’t follow this simply because we don’t love the design of Google’s products

time0ut 6y ago

Great article. I spend a lot of my time writing design docs these days. We derive a ton of value from it. The projects I work on are typically collaborations with several developers. It is important to all have the same vision for what we are building. A good design doc is a vehicle for a team to sync their mental models of the thing they are building. We also often have many other teams (security, infrastructure, operations, other business units, etc) who all have a stake in what we are doing. A good design doc helps build consensus with them. The review process gives them a voice in calling out concerns. It is much easier to solve a foundational problem before any code is written. One addition that isn't explicitly called out by the article, but I have found very valuable, is the inclusion of references. In my experience, good design docs typically include some references. Links to the docs for a piece of software we want to use, links to an AWS blog post explaining part of the architecture we want to use, links to academic papers explaining the algorithms we want to implement, etc. Good references support the design doc and help readers fill in knowledge gaps they may have.

bigbizisverywyz 6y ago
>It is much easier to solve a foundational problem before any code is written. This brings to mind the 1-10-100 rule. It takes 1 unit of effort to fix a problem in design It takes 10 units of effort to fix a problem during development. It takes 100 units of effort to fix a problem after going live.

ChrisMarshallNY 6y ago

I'm of a mind to reduce documentation as much as possible, or keep it as vague as possible. That's because I came from an environment that insisted on incredibly detailed, formal, approved-by-everyone-including-the-mens-room-attendant, documents. These became "concrete galoshes"[0] that turned what should have been an agile, iterative project into a waterfall behemoth that cost a mint, took forever to make, and delivered a result that no one wanted. I suspect that my current process[1] would not be acceptable for many organizations, as it basically requires that everyone involved be extremely experienced, and kept together as a team for years. I've actually come to realize that "tribal knowledge" is not the boogeyman that its made out to be; but is a way to get very high-quality, rapid, adaptive, development done. The main issue is that it does require good, empathetic management, long-term retention of experienced, capable people, and an "apprenticeship" model. These are not popular concepts in today's corporate world (at least, in the US). [0] https://medium.com/chrismarshallny/concrete-galoshes-a5798a55af2a https://medium.com/chrismarshallny/concrete-galoshes-a5798a5... [1] https://medium.com/chrismarshallny/forensic-design-documentation-54541925d30e https://medium.com/chrismarshallny/forensic-design-documenta...

lhorie 6y ago
I think something people need to be aware of is that the engineering culture at places like Google is extremely different than, say, a bank. Design docs work well for Google because it has decentralized, independent engineering teams composed mostly of reasonable people, with few or no mandates from outside their teams. They tend to fail at companies with underperforming, micro-managing, and/or overreaching teams (e.g. unionized project managers that have literally nothing to do, bizdev telling developers what features to implement (down to specifics), QA teams who are incentivized to find "flaws" ad-infinitum to look busy, etc). But I see this as a symptom of a fundamental dissonance in goals. Design documents are used by organizations whose goal is to build/change things. Many organizations are averse to change, and their processes reflect that, through overly microscopic documentation, convoluted approval chains, etc.
- ChrisMarshallNY 6y ago
  Yeah, you are correct. But I have become rather cynical about the motivations of a lot of organizations, these days. Everyone seems to be promoting an environment where there's a constant circulation of relatively inexperienced (not always low-paid, but inexperienced) developers, staying at companies for short periods of time, then moving on. This requires a codified, ingrained structure that needs to be documented and supported. It applies to modern, "agile" companies, as much as it does to more traditional, "hidebound" corporations. People that come in need to be onboarded quickly, squeezed for every ounce of productivity possible, then let go, when they are no longer useful. This is supported by the employees, as much as by the managers. The salaries can be quite high; especially for people that are quick to adapt and come up to speed. But there is absolutely no substitute for an experienced, cohesive team that has developed a shared vocabulary and focus. I was fortunate to be a member of such a team. The person with the least seniority on the team had a decade. Everyone had over 30 years' experience in software development, and we got some fairly intense stuff done. Sadly, we were still subject to the kind of structure I mentioned above, and a lot of our product ended up being housed in substandard wrappers (we did "engine" code).

commandlinefan 6y ago

I like the idea of design documentation, but in 30 years of software development experience, I've never seen one done well. TFA does a reasonably good job of outlining what you'd want from an ideal design document but doesn't offer any advice on creating one that actually meets these criteria.

colonelxc 6y ago
One trick google uses is that there are 'standard' templates to start your design doc from. So it has all the sections mentioned in the post, and each section is initially filled with a description of what is needed there (and sometimes links to other supporting materials). Not everyone will be diligent and fill out all applicable sections, but it does help bring some uniformity to the process.
AgloeDreams 6y ago
Basecamp pitches and shaping are kinda like design docs but with a lot of what I found to be lacking here? You might want a look, they they refreshingly human-readable concepts.
gowld 6y ago
Same could be said for code, right? It's a great idea, but in 30 years we've never seen code done well. "Well" is a slippery word.
- commandlinefan 6y ago
  But code actually works (eventually, usually). If you don't have code, you don't have software. If you don't have a design document... it's usually the same as if you do have a design document.
  - etse 6y ago
    In my experience, it’s not the same. Design docs allow a dialogue about the resulting code that code reviews are poorer at or less efficient at. Those conversations have saved us time and gives us confidence that the solution is the best for the problem.

mediocreguy 6y ago

Any good examplars of docs that use this format?

Slump 6y ago

Great article, generating consistent design docs that are both useful and not too time-consuming to create is something I am constantly working on. One thing I struggle with is finding examples of what others are doing in the industry. Does anyone have any resources they've found that provide examples of real-world design documents? Obviously each project is different but I'd be curious if others out there are publishing their templates/outlines of what they typically start with similar to this article. I feel like blog posts seem to serve this niche for a lot of open source projects but it would be interesting to see if anyone has found more structured examples.

PascLeRasc 6y ago

Does anyone know where to find real examples of design docs, possibly following this guide? I don't mean toy examples but something that's actually used by real people/orgs. My workplace has design docs but they're full of made-up words, so I'm pretty burned out by this kind of thing.

Offpics 6y ago
Deno design doc for example https://docs.google.com/document/u/0/d/1_WvwHl7BXUPmoiSeD8G83JmS8ypsTPqed4Btkqkn_-4/mobilebasic https://docs.google.com/document/u/0/d/1_WvwHl7BXUPmoiSeD8G8...
- PascLeRasc 6y ago
  Thanks! That was interesting to read and gives me hope for a better workplace. So it's basically a much more thought-out Github issue/corresponding PR, would you agree?
yegle 6y ago
The author of Beancount (a text based accounting software) is a Googler and he recently shared https://docs.google.com/document/d/1qPdNXaz5zuDQ8M9uoZFyyFis7hA0G55BEfhWhrVBsfc/edit?usp=drivesdk https://docs.google.com/document/d/1qPdNXaz5zuDQ8M9uoZFyyFis... which is a pretty standard Google style design doc.
vially 6y ago
This is one I follow related to adding multi-window support to Flutter: https://flutter.dev/go/desktop-multi-window-support https://flutter.dev/go/desktop-multi-window-support I also found some of the chromium design docs quite interesting: https://www.chromium.org/developers/design-documents https://www.chromium.org/developers/design-documents
cpeterso 6y ago
Python's PEPs (Python Enhancement Proposals) are pretty good examples of design docs that describe the problem, proposed solution, and rationale: https://www.python.org/dev/peps/ https://www.python.org/dev/peps/

Areibman 6y ago

>Finally, the overhead of creating and reviewing a design doc may not be compatible with prototyping and rapid iteration. However, most software projects do have a set of actually known problems. Subscribing to agile methodologies is not an excuse for not taking the time to get solutions to actually known problems right. Here lies the biggest problem with the article. Most software projects _do not_ have a set of actually known problems. Agile exists precisely because it's hard to pin down what problems are, and you learn much more about your product with gradual experiments than with some grand, centralized design. Unless you are totally certain about your solution, design documents don't have a place for most projects.

bdefore 6y ago
While I agree, I find this common argument to have a faulty rhetorical approach. Leadership can often be allergic to allegations that there are problems that they don't know about. They can be outright defensive towards suspicions of uncertainty. I feel there may be a better way to express the utility of rapid iteration and design-as-you-go without triggering a fight response.
theptip 6y ago
I don't agree with this viewpoint. Agile is about just-in-time design, not no-design. At some point, you need to decide what the next increment you're going to build is. Before you write the code for that increment, you have by definition picked an actually known problem to solve, and for that you should write a design doc. I think what you're objecting to is the waterfall concept that you would write a design doc that covers the whole project, rather than just designing what you're going to work on next. I can wholeheartedly agree with that objection. However everything in the article is consistent with epic-level or story-level design. As the complexity and cost of change increase, more up-front design is appropriate. None of that is incompatible with the agile tenets of building small increments and delivering them often to make sure that they add value. If you're lucky enough to be working in the early stages of a project with a few thousand lines of code, and little to no production data on which to maintain integrity, then the value of formal design docs goes way down. But it's important to know that you'll need them later.

jhallenworld 6y ago

Design docs should be written in Markdown and stored in git. The advantage here is that the git hash can be used as a legal reference, for example in the case where a contractor is expected to implement the design.

dilyevsky 6y ago
I’ve tried this and I tried just gdocs like everyone at google did. Gdocs seems better for iterating because github review ui sucks (and everyone else sucks even more). If google critique was publicly available I’d much prefer markdown for designs
- pmb 6y ago
  The best is to get agreement on the design is gdocs and then export it to Github so that the design and code live next to each other.
bbeekley 6y ago
We did this at a previous company in the healthcare space. It made audits easy since we could point to every instance of the design changing, who approved it, and the code that implements the change (all wrapped up in PR(s)). In general I like checking docs into source control, for all the reasons we use git and code reviews for the code itself.

nkingsy 6y ago

The emphasis on trade offs is the most important part for me, because it formalizes the search for alternative approaches. In the majority of my design docs, I end up swapping an “alternative” into the doc itself as I find myself more convinced by the alternative solution.

lowiqengineer 6y ago

I wonder why the "at Google" is necessary for the title. I'd be very surprised to see an organization not use some sort of design doc before building things - the only thing that would be different is the scale and scope of them. Of course, you won't see a "Design Docs at Amazon" on the front page of HN for...some reason. Gee, I wonder why?

AnonC 6y ago
> I'd be very surprised to see an organization not use some sort of design doc before building things - the only thing that would be different is the scale and scope of them. There are companies that use agile methodologies and eschew any kind of design documentation (they kneel at the altar of working code, and working code alone). I’ve seen teams just discuss things, get a few inputs and start writing (working) code and pass it through testing. The design process exists, but there’s no document or documents for anyone to refer to. There may be high level architectural documents, but not what many people understand as “design documents”.
- sateesh 6y ago
  I always wonder how such an approach works towards building maintainable software whose scale is not trivial. Even assuming the code is reviewed unit tested, but still without some kind of design doc guiding the overall structure, and interactions wouldn't it lead to hard to maintain software ?

dgb23 6y ago

Related: https://www.joelonsoftware.com/2000/10/02/painless-functional-specifications-part-1-why-bother/ https://www.joelonsoftware.com/2000/10/02/painless-functiona... My opinion: If you don't specify things in a separate document in the form of text and pictures, then you end up doing it anyway but ad-hoc. Your "non-spec" now leaks into multiple tools and channels that likely don't talk to one another: emails, instant messages, file storage, notes, phone calls & discussions (AKA in your head/memory), Trello/Asana/Jira etc. and in peoples imaginations and expectations. A specification is just the things you do anyway but instead written down in a single maintained place. You can source control it and iteratively change it. All the parties can pull it and look at it before/during/after iterations and discussions. A spec doesn't need to be set in stone at all. It can grow/shrink/change iteratively with the thing you build. It can also define things that you specifically shouldn't do or worry about. A "design doc" seems to be something like that with a different name? Also a specification can help to communicate much more clearly, since you end up defining a vocabulary for processes, UI elements, technical components and so on. Tools I find useful to do this: - markdown + css + some tool to convert it to html/pdf - graphviz, especially for state-machines and decision trees, I prefer output as SVG rather than PNG. - UML diagrams or similar if applicable

bigbizisverywyz 6y ago
A really nice framework for specifying a system, I've found, is the vision document from RUP. It's great for putting the user front and center, and ensuring that you're building a system that people actually want and have a realistic business case.
H8crilA 6y ago
A design doc is not exactly a spec. It is a medium for discussion and a snapshot of what people thought at the time. They do get old pretty quickly and there's no expectation that anyone will update them (always put dates on such documents!). I think that specs should be checked into the codebase, either through some kind of code annotation, or next to it in text files, depending on what is it that you're doing.
- 6y ago

eximius 6y ago

Half the time these are written after the fact (or updated after major changes), so they're often used as shitty documentation. I don't disagree with them, in principle, but I've yet to really see the benefit of them. The adage "In preparing for battle I have always found that plans are useless, but planning is indispensable" seems to apply.

the_arun 6y ago

Do we have any templates for design docs created by Google, Facebook, Twitter etc.,? Not to be negative - My problem is there is no spec/standard template for design docs (like someone compared it with Blueprints). If we have a template approved by industry leaders - it will be convenient. Otherwise everyone creates them in their own way - convenient for their use cases. But this will miss the consistency and all necessary ingredients. This ends up these docs fading out with time. Also, when design changes - these docs need to be updated. People don't do this. After a while, design docs become obsolete & overhead.

thebrokencube 6y ago
I think if there was a rigid spec, it would work against one of the points made early on in this doc (which I think is worth taking note of): > Rule #1 is: Write them in whatever form makes the most sense for the particular project. This is an unsatisfying rule, but I think it's important because each team/problem space/etc. is different and too strict of rules can often lead to documents that may end up being shallow. However this admittedly doesn't help with this other problem you brought up: > Also, when design changes - these docs need to be updated. ... but that may be okay given a shared understanding of what the goal of said document is. If the goal is to gain consensus around an implementation (as opposed to it being a living document), the document may have served its purpose by the time that consensus is reached, even if later on the design changes. If the goal is to have living documentation of a system, then maybe the rough format specified in this article isn't correct. One term I've heard for design documents is that they end up being a piece in a "Decision Log", which has helped me feel less bad if the document falls out of date. These documents end up being more point-in-time representations of the collective understanding/opinions of how a specific project/system was being thought of, and that has its own advantages even if it falls out of sync.
- brown9-2 6y ago
  The first points here are absolutely correct. These documents are a way to communicate and get feedback (and iterate) on an idea with a group of people in your organization. Different organizations will communicate differently, and have different needs.

vngzs 6y ago

IMO the ideal format for conveying this information is to show, not tell. Give me an example document and annotate it with sidenotes that describe the purpose and importance of each section. Then we get to see how well it works, not leave it up to imagination.

whoevercares 6y ago

Frankly I think Amazon has a even heavier design culture. The designs for a new project (e.g to be launched at reinvent) could go as long as more than half year.

koheripbal 6y ago
Does duration really measure depth of design?
- whoevercares 6y ago
  Yeah some are churns from reviewers, partner teams or even politics. The depth of the design are commonly pretty deep to the ground, because Amazon has many SDE1s with relatively low hiring bars and the design need to be super detailed for a safe execution
  - akhilcacharya 6y ago
    > SDE1s with relatively low hiring bars as an SDE1...yikes dude.
    - whoevercares 6y ago
      Sorry I mean compared to Google/FB... But that doesn’t translate to productivity though
      - akhilcacharya 6y ago
        Again, that's a major yikes. I really don't think many others like me enjoy being called, er.., dumb.

cborenstein 6y ago

Design docs are great because writing them is aligned with the author's best interest, not just a future reader. (This is different from docs that are written after the project is complete). Design docs help you understand the project, identify dependencies, and avoid repeating work. Then they leave a trail for future engineers of the thought process that went into the code.

jeffbee 6y ago

A fun activity if you’re a Googler is to go read ancient design docs, like the original pitch for bigtable. They are pretty short for the most part, and they were written by the legends. These are the Federalist Papers of your company, they give real context to how the company arrived here. In particular I always enjoyed reading the jarring parts were they describe something that definitely did not make it into the implementation, or got removed later. It’s interesting to think about why they considered those things important enough to write down at the time. Now that I wrote the above, it's a bit sad that there aren't many design docs for open source software, even ones that originated from companies with good design doc culture. Where's a doc that discusses alternatives considered and rejected for kubernetes or grpc?

spelunker 6y ago
Great advice, jeffbee! hey wait a minute.
jbeda 6y ago
I wrote a design doc/PRD for k8s that outlined the basic API, distributed structure and why/how it related to open source and the marketplace. I lost it when I left google. It was a google doc IIRC and wasn't checked into source control.
- robk 6y ago
  Someone must have shared access to find it for you though?
mleonhard 6y ago
Those "legends" joined the company very early and had opportunities that don't exist today. Why idolize them? Some of them are not good people. There are plenty of people who would do legendary things if the company let them.

Ozzie_osman 6y ago

Honestly I sometimes write a design doc even if no one else will read it. It can be as short as a few sentences, if needed. The main benefit is it forces you to: 1. Think strategically, not tactically, about what you're about to build. Beyond just "I need to get this working now". 2. It makes sure you can describe what you're about to do in plain English (or plain English plus some diagrams). If you're struggling to do that it's probably a sign you need to rethink your approach. Obviously, the organizational benefits described in the link are really important, too, but if all you've done is just 1 and 2 above that's already worth your effort.

petejames 6y ago

Writing helps you think. In the process of creating a design doc you get clarity of thought and refinements happen.

jkaptur 6y ago

It's important draw a distinction between a "design doc" and "documentation". tl;dr: "ought" vs "is". A "design doc", as described in the article, is a tool to help make a decision. It's a proposal. It is "ought". It describes the state of the world at a point in time, the desired change, and how to make it. Once the decision is made and the work is begun, it's rarely updated. "Documentation" is just the state of the world (generally "now" or "at release x.y"). It describes the design and use of the system, but has very little digression into ways it could be different. If it links to a design doc, it should be for Once you draw this distinction, it's clear that design docs should be in something like Google Docs, while documentation should be in something like a wiki or git. It's clear why it's fine for a design doc to be out of date, but it's a big problem if documentation is. etc.

jp42 6y ago

After reading this article I can relate it event trace (Chrome tracing) design doc form google, very succinct to the point: https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview# https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQt...!

jeffbee 6y ago
That is not a design doc, that is a format specification. It jumps directly to the implementation details without discussing the motivation. The reader has no way to evaluate the utility of the example JSON because the doc has not stated any use cases.
- cmrdporcupine 6y ago
  And frankly that's how most of the design docs at Google really are. They're post-facto descriptions put together for the purpose of gaining promotion.
  - jeffbee 6y ago
    Yes and the way you can tell is the doc title is "FooBar Design Doc" but the shortlink is "foobarforperf".

juanbyrge 6y ago

It's a little ironic that the author of that post created AMP...

gregdoesit 6y ago

“Unstructured text, like in the form of a design doc, may be the better tool for solving problems early in a project lifecycle, as it may be more concise and easier to comprehend, and communicates the problems and solutions at a higher level than code.“ I could not agree more. I came across the concept of design docs consistently used for all projects at Uber. They were called RFCs here and they were introduced very early on. I wrote in more detail about my experience using these and how I am pretty sure they helped scale the engineering culture [1]. The most surprising thing I’ve observed is how sending these design docs out to all of engineering worked really well, until the org was over a thousand engineers. [1] https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/ https://blog.pragmaticengineer.com/scaling-engineering-teams...

wsetchell 6y ago

The article does not point out how the system can go astray. Design docs are great when they can in 1-2 pages describe a how an important/large/complex system will work and the tradeoffs made when designing it. Some groups in Google confuse design docs conflated with the promotion process, and thus engineers start create long/time consuming docs for every little thing as part of building a case for promotion.

blargmaster33 6y ago

Properly done MIL-STD-498 is a joy to behold. Operational Concept Description (OCD) - Used to sync with the marketing/sales non technical people. System/Subsystem Specification (SSS) - Software/System architect and agile team leads sync here System/Subsystem Design Description (SSDD) - Developers documents a rough outline of how stuff was done.

bruckie 6y ago

I find design docs really useful, even if no one else reads them, because they force me to clarify my thinking before I start the (more expensive) process of implementation. However, I've also noticed a couple of very common problems with design docs: - Many design docs don't clearly state the problem that the design is intended to solve. Often the best response to a design is "that problem isn't important to solve", or "there's another system that already solves this problem", or "there's a totally different approach that you should consider", but without a clear statement of the problem and why it's important to solve, it's hard to determine those kinds of things. - People often focus too much on the details of a design, vs. the important decisions that need(ed) to be made, the alternatives and rationale for those decisions, and the assumptions that they were based on. In a year, you probably won't care that much about the details of the parameters of some API, but you probably will care a lot about why you chose that API over some other one, and it's useful to have a record of that decision. It's useful to view a design doc as a distillation of the thought process behind a system, vs. a high-level description of how to build something.

justicezyx 6y ago

Hah, design docs at Google... I read probably hundreds of deigns docs during my 6 years at Google. I think among them, only a handful of design docs, like < 10, are considered clear, clean, and succinct. And all of them are more or less retrospective ones summarizing a system after it's already being implemented and running for a while. The newer design docs, which are served as actual working documents for an active projects, are no doubt primarily a process mechanism to solicit design inputs, and garner supports from stakeholders. It is a formality to show that the project owner is willing to waste his time and to convince so-called "reviewers" about the validity of the project. The reviewers usually do not read the design doc in earnest. Only the stakeholders, like the TL of the team, potential customers, partners, would spend serious time on them. It's more or less a debate ground for stakeholders to pointing fingers at the design process. That's also why the design doc is written in Google Doc in the first place. Once a design is "approved", it usually means from most major share holders are satisfied, to everyone is wearied down enough and the project has enough importance to actually push forward, they are OKed for implementation. After that the design doc is largely useless, the designs laid out in the doc is usually 1) too simple that there is no need to consult design doc anyway, one can explain it in a few minutes chat; 2) too complicated that the design diverges from the actual code that the design doc offers little guidance. And very few design docs sit in between. All in all, anything produced during a software engineering project seems all is about being a tool for organizing the human interaction process, the artifact, aside from a very high-level motivational piece, and the end result code + docs, whatever in between seems largely bears little value after the work is done.

choppaface 6y ago

It would be great to see some actual design docs in a blog post versus a summary article with zero primary references. (A postmortem of some design docs would be incredible!). One of the hardest things about introducing a design doc process to a team of engineers is providing concrete examples as seeds and ensuring feedback to make the process actually work. It can be really jarring to introduce the design doc philosophy to a larger team if all they've been doing is Scrum every week. Moreover, typically design docs happen at a quarterly rhythm and feedback periods can take weeks-- this slow cycle is a major impediment to consensus and learning. All this calls for material that speaks to differentiated learning. Extolling "we do this at Google" is a leaf in the wind.

floil 6y ago
Here you go: https://www.chromium.org/developers/design-documents https://www.chromium.org/developers/design-documents

staplung 6y ago

I worked at Google for 4 years. One thing that has always surprised me about documentation at Google is that they use Google Docs (just like everyone else) but have never seemed interested in making it less of a terrible tool for the task. It's relentlessly print oriented, which makes almost no sense these days (when was the last time you printed out a Google doc?), has no affordances for dealing with pre-formatted text (e.g. code), has basically no support for mathematical formulas, etc. In fact its actually evolved to be less suited to the task of technical documentation since it began given that earlier versions at least allowed you to define your own paragraph styles. I was hoping that Google Colab might evolve into a better/more general tool for writing tech specs but it doesn't seem to be moving in that direction really.

maxwellg 6y ago
Comment discovery is also horribly broken. So often, conversations _about_ a document contain information that don't necessarily _belong in_ the document, but still have value for future readers. Resolving comments makes it much harder to find them.
xnx 6y ago
Exactly correct about the print-oriented interface. Writely, and earlier versions of Google Docs didn't force you to pretend you were writing on a piece of paper. I would love a "Google Docs for text files"!
akhilcacharya 6y ago
At my company we use the internal Wikis or Quip for this. Versioned and effectively markdown formatted with builtin live charts or spreadsheets, respectively.
- galkk 6y ago
  Amazon had both wiki and Quip, and both were bad, but differently. Wiki was painfully slow to edit (and render, ~2 sec page render was typical, and I'm not counting some graphs that were asynchronously rendered). Quip is good for fast editing, but anything that needed code formatting there is bad. It's even more "print oriented" than Google docs. Fixed page width, very fixed formatting, tables are awful.

rckoepke 6y ago

I'd love some examples of real-world design docs.

mbakke 6y ago
The Ganeti virtualization toolkit which was developed internally at Google and released as free software is full of such design docs. I always enjoyed reading those as an external Ganeti user: http://docs.ganeti.org/ganeti/master/html/#implemented-designs http://docs.ganeti.org/ganeti/master/html/#implemented-desig...

kcudrevelc 6y ago

I've worked at Google for a while, and a few years ago I wanted to release an open-source project. Since the code was going on Git, it made sense to throw the design there too, so I just added a DESIGN.md to the top-level of the project. This has had a remarkably nice effect: sometimes, when people make large changes to the project, they update the design to reflect the changes! See this lovely commit as an example: https://github.com/google/stenographer/commit/d678531a3e5a87b321e9247ba60d0019768681de#diff-6a735bf86dcc8fb712e11c207df01ae4 https://github.com/google/stenographer/commit/d678531a3e5a87...

maps7 6y ago

This is awesome! Thanks for posting - I think I can use this where I work. I am wondering though.. how do you allocate time to work on the design doc? I'm sure sometimes it takes a day but other times it can take longer and if there's a review needed then it would take even longer. I work in a agile/scrum team - how would this work fit in there?

winrid 6y ago

At a medium sized company/startup that follows this pattern. It works really well. Much better than the core platform team just going and changing a bunch of stuff every release with no documentation, which I've experienced consistently at my last job.

blululu 6y ago

This is a very optimistic presentation of design docs. The flip side is that these documents can become a touchstone for bike shedding or and excuse to make slideware in lieu of software. A lot of administrative bloat can creep in through design docs.