13 ms·

Design docs at Google (2020)

• hehdhdjehehegwv 2y ago
  [flagged]
• leoh 2y ago
  Does anyone know where to find a copy of go/greendoc?
  • lrem 2y ago
    Why would you? If you feel the process is worthwhile replicating elsewhere, just use your own words for the couple paragraphs of instructions.
    • leoh 2y ago
      I don’t even really remember what the sections were any longer
  • danpalmer 2y ago
    There's almost nothing in the greendoc template, I'm not sure it's at all valuable outside of Google.
    • leoh 2y ago
      I worked at Google and respectfully disagree
      • danpalmer 2y ago
        Perhaps you're thinking of a different doc, or perhaps it has changed. I went to check it and it's literally 2 pages with 5 headings (all mentioned in this post). There are some other much better ones in my opinion, and some great internal docs on writing and examples. I wish those were public.
        • leoh 2y ago
          Not really, I think that’s it actually.
  • runeblaze 2y ago
    It is useful but at the same time different teams IIRC had different design doc structures. I was overwhelmed by go/greendoc when I was an intern and I just opened an empty doc and started writing based on my team's existing design docs... and that worked better. In the end it is just technical writing.
• yareal 2y ago
  Design docs are great, but Google's writing culture is highly fragmented and quite disjointed. I much prefer Amazon's writing culture (despite hating absolutely everything else about Amazon's culture.)
  • bushbaba 2y ago
    Amazon uses writing to bias for action in meetings. Their culture has DRIs (or dictators) who have authority to make the call, with such authority coming with some level of accountability to the decision made. At Amazon the doc is read, parties discuss, and decision made. At Google the doc is rarely entirely read, mostly commented on, and no decision made until all stakeholders align on a commonly agreed direction. The amazon way is much less toxic, but does come with a need for writer to invest heavily on a high quality doc. Personally, the Amazon way is better but only works due to their peculiar culture.
    • spondylosaurus 2y ago
      Amazon has famously high turnover, doesn't it? I wonder how much their investment in docs is downright critical to keeping the ship afloat—otherwise people leave and take all their knowledge with them. But if it's written down you can pass the torch.
      • iLoveOncall 2y ago
        After working there for 6 years, I haven't seen a single up to date design doc. At best a high level diagram. They are outdated as soon as implementation start, by different degrees depending on the project. Side note but I think this average tenure number hasn't been updated in a very long time. In London for example, a third of employees have been here for more than 5 years.
        • dbish 2y ago
          US (where bulk of employees are) is still pretty close to 2 years unless that changed a lot in just a few years (I was a sr. dev manager there and worked there for around 6.5 yrs). This is pretty similar to the rest of big tech though except for Microsoft. England and Europe in general is a bad comparison since they have fewer options and very different working expectations.
• jongjong 2y ago
  This is a great habit. I wish all projects had a coding style document. Coding philosophy is much more important than tooling and choice of languages IMO. Not having such style guide is like employing builders on a construction project without letting them see the plan. That said, about this point: - Ensuring consideration of cross-cutting concerns. My answer would be "Avoid cross-cutting concerns because they are a violation of the separation of the concerns principle; a violation of the cross-cutting kind" ;p My observation is that while avoiding cross-cutting concerns can seem challenging at first, creating a code architecture which avoids them leads to much more maintainable and easy to follow code. I've worked on many complex projects; distributed systems, blockchains, P2P messaging systems... but I'm yet to encounter a project which cannot be structured in a way to avoid cross-cutting concerns completely. That said, IMO, aspects mentioned in the article like "security, privacy, observability" aren't really separate 'concerns' but merely desired characteristics of software components.
  • dpe82 2y ago
    Perhaps read the section dedicated to this point: https://www.industrialempathy.com/posts/design-docs-at-google/#cross-cutting-concerns https://www.industrialempathy.com/posts/design-docs-at-googl... Some cross-cutting concerns are about more than just code, but things like "how will you monitor this for reliability?" or "this system reads user-sensitive data, how will those reads be audited?" and so on. Usually the answer is short: "use standard system xyz" - but having it there and ensuring it's followed through on are important.
    • jongjong 2y ago
      Fair enough. Definitions can be broad. The term "Cross-cutting concerns" made me think of aspect-oriented software development which has a very specific definition and it tends to favor specific approaches like dependency injection. For example, in aspect-oriented development, they tend to promote injecting a logger into all the components; but other development methodologies might instead make it so that messages and errors bubble up the component tree (e.g. for non-error messages, might use event emitters, message passing, callbacks, or other kinds of channels). But the idea is that the messages for all components are aggregated, handled and logged near the top level in a central place; so you don't need to inject a logger instance into every component; it loosens the coupling of your components with the rest of your application... Also, logging might be just one of things you do with those messages. It's nice to have that logic near the top level of the code. I find it extremely valuable when the important outputs of the system (what the developer or user can physically observe) can be traced starting from a single source file (or at least, as few files as possible).
• s17n 2y ago
  I feel like at Google, design docs suffer from being the main thing that goes in your promo packet, which leads to the writing being done more with promo committee in mind then the documents ostensible audience of people who are working on the system the document pertains to.
  • underdeserver 2y ago
    I'm not sure what the difference is, except giving more context than teammates need, or trying to make a problem more complex than it is. By and large I didn't notice that strategy working. On the other hand, for context, people wrote large docs on what the team did and does, what the problems are, etc. and those did tend to be long and exaggerated.
  • dietr1ch 2y ago
    This makes many docs follow the pattern of a more complex design when its completely unnecessary. All just to get more "perf points" from the people that only have time to skim through the docs. I read many docs that, to me, obviously made up a decision and showcased the thing we already wanted by the time the doc was started, and 2+ silly alternatives (at least one way too simple and an unnecessary overkill) and contrasted them to pick the thing that was reasonable.
  • kaon_ 2y ago
    True for every employer i've ever been at. Your career is mostly steered by exposure, rather than reputation or ability. Design docs are very visible to those above you. At yvery company I join, I propose we start writing design docs. It immediately puts me in good standing with management :)
  • r0ze-at-hn 2y ago
    Devs straight up tell you that they write design docs for the promo committee. That is their goal, everything else is secondary. Given that they never know which design docs they will use in their promo packet they put everything they work on in design docs no matter how small. There is the idea of a one pager design doc, but usually they grow from one page to ... many. It might be a one week project, but a design doc gets written. I have also had to reviewed 20, 30, even 40 page design docs that took clearly a while to make and at any other company would be simply a JIRA ticket. I have had discussions about how many pages is too many and if we should have a limit etc. Too many have learned (correct or not) that promo committees want to see that only the author wrote a doc and no one else. This further slows down everything and disincentivizes cross learning. I know software engineers who spend a full quarter or more in isolation writing design docs. The majority of the writing in a design doc is the actual design, but the other 99% is the definition of the problem. Too many times I have been in a review and spent a bunch of time improving the definition of the problem which results in the design needing to be scrapped and most of the doc needing to be re-written. Worst case scenario is when by improving the problem definition a simple solution appears that doesn't require a complex design. The author having invested a lot of time in a complex design (that historically and many committees still look for to promote off of) will push back against anything that is simple. The difficult trick is helping the engineers to improve their problem definition early in the writing process. I have seen design docs that have no alternatives presented. The design doc was simply a labor intensive way to write down what needed to get done or what someone wanted to do. This also results in design docs turning into a bug tracking system if you squint. In a hand wavy way everyone is working on their design doc, not bugs, bugs can't get you promoted. And OP like to wax poetically about how when you join a team you can just go and look at the design doc like that is a simple and obvious thing. They are often not tracked in any central place. For many teams design docs are not owned by the team or the project, but by the individual because you can make sure no one else contributed. This is again for the promo committee sake. Many design docs you can't get access to, not because they are super secret, but just because. And it isn't like teams have say two or three design docs, no there is a mountain of design docs to read. And with around a two year turn over at Google many design docs get lost to time. At any other company this could be like if you joined the team and I said everything you need can be found by reading all the closed bugs or read every commit message in the main branch. Anywhere else I would have been grabbed after lunch and would have worked on defining the problem for a few hours with the team at the whiteboard. The senior members teaching the younger in real time how to think about these things and iterating quickly. Most of the time this would be written down in the bug tracking system or for bigger stuff in the project's wiki/folder to be owned by all. All of the above can be improved and I have worked on improving all of them, but culture is a slow thing to change. Design docs are a good idea as a concept, but there are pitfalls and the way they are being used by many (not all!) at Google is not it.
• dudus 2y ago
  And on the product side you have product requirement docs which was always useful when a new feature came up as it aggregated all contacts, documentation, support, communications, etc. You always want to work in a product that maintains a decent one.
  • smokel 2y ago
    > You always want to work in a product that maintains a decent one. That'd be lovely indeed. I have never seen one that I felt comfortable with, though. And I've seen a few. When LLMs rose in popularity, I had hopes of having a way to tackle the problem of formulating requirements in a way that would be less painful than it is now. To me, computer programming is a form of communication, where the requirements are close to humans, and program code is nearer to the machine. On the computer side, we have linters, compilers, and a deterministic system that executes the code. On the human side we have people stating requirements such as "The system should be easy to use."
• _obviously 2y ago
  Remember, Google retains the right to copy databases as they're not copy protected.
• SSchick 2y ago
  Design doc culture at google is why I left the company. I wrote a very high level doc shortly after joining the company outlining a fairly trivial task (one that has been performed many times across other product areas). A colleague virtually took me aside and told me "this is not how we do things here". Which was kind of a wake up call as he told me to make sure to 'evaluate many more ways to get this done' despite the way I outlined literally being a slight variation on the recommended way. When questioned about why this would be needed he said "it shows broad consideration". "Fake work" is very much a thing at google, I wish I joined a different team.
  • devjab 2y ago
    You have a point in that bureaucracy can needlessly get in the way of meaningful change. It frankly always will to some degree. That being said, part of the way you make sure it gets the least amount of in the way is to standardise it, and actually enforce those standards. From your description you fall into both categories, which means your colleague was correct. Now, your amount of details is very scarce, so it’s extremely likely that I’m getting the situation wrong. But look at it from an enterprise level perspective or change management, if you allow slight deviations here and there for thousands of employees then you’ll very quickly end up with what would be the equivalent of the difference between Italian, Spanish and French. Which all shares the same Latin “standard” and then deviated ever so slightly. If you think there is a lot of pseudo work involved with managing the bureaucracy of enforcing a design doc standard then you should see just how much pseudo work it saves.
    • SSchick 2y ago
      I don't disagree, hence "fake work" in quotes. Some people may (and clearly do thrive) in such environments but I personally did not. This particular scenario was a simplified excerpt but very well captures my perceived experience. Having to write a design for for something that was a solved problem (by a team maintaining a framework) felt like pure busy work. If there was a higher meaning to this process this higher meaning (other than looking good / getting promoted) was not communicated in any effective manner. Maybe I'm dis-illusioned with the current culture in big-tech but a promotion should be a result of doing good work, not doing work that is designed to look good. And yes I understand that some of these mechanisms may exist to provide employees a clearer path for ascending the corporate ladder.
• ndjshe3838 2y ago
  1. Creation and rapid iteration 2. Review (may be in multiple rounds) 3. Implementation and iteration 4. Maintenance and learning Missing step 5: Promotion and deprecation
• billfruit 2y ago
  Can we see some real documents? It is as if software design process documents are the closest guarded secrets, because I have never seen a real document being available for case study.
  • rullelito 2y ago
    Companies keeping their IP a secret? Weird..
  • faizshah 2y ago
    Chromium: https://www.chromium.org/developers/design-documents/ https://www.chromium.org/developers/design-documents/ Kubernetes: https://github.com/kubernetes/enhancements/tree/master/keps https://github.com/kubernetes/enhancements/tree/master/keps
    • iainmerrick 2y ago
      Thanks for these links! I picked out one at random just to check if my skeptical reaction is fair: https://github.com/kubernetes/enhancements/tree/master/keps/sig-architecture/4402-go-workspaces https://github.com/kubernetes/enhancements/tree/master/keps/... - OK, this is actually a really good and useful doc! - However, it's not an up-front design doc, it has clearly been written after the bulk of the work has been done, to explain and justify rolling out a big change. (See the "implementation history" timeline: https://github.com/kubernetes/enhancements/tree/master/keps/sig-architecture/4402-go-workspaces#implementation-history https://github.com/kubernetes/enhancements/tree/master/keps/...) - It looks like the template wasn't very useful; most of the required sections are marked "N/A", and there are comments like The best test for work like this is, more or less, "did it work?"
      • jppittma 2y ago
        Google is a huge company with ~180,000 employees. Sometimes people do sensible things.
        • 2y ago
• ajkjk 2y ago
  Does it work? Is it better than alternatives? Where's that discussion? I worked at Amazon and their design doc culture was amazing. My next job was at a place that (I think) borrowed their engineering culture from Google (or maybe the ambient startup culture of SF?) and their design doc process was a pointless joke.
  • r0ze-at-hn 2y ago
    Which aspect of the Amazon design doc culture that you loved the most?
    • ajkjk 2y ago
      How intellectually serious it was. The treatment of docs was an extension of how they treated engineering in general, which was, seriously and critically. For the most part good engineering took precedence over politics and promotion material and shiny new stuff, unlike what it sounds like you get at a lot of companies. (disclaimer: very org dependent, as all statements about Amazon are.)
  • blueboo 2y ago
    Design docs are vehicles for discussion. The idea is that they are the most efficient way to communicate your intention, motivation, why not alternatives. They are one mechanism that fits in a broader working culture. If you’re working solo, it’s an extravagant exercise. If you’re in a huge team, it’ll enable leveraging more expertise across the team and act as documentation. There are a few different failure modes. * Valuing output not outcomes is classic misalignment. (writing 40 page docs for promo — this doesn’t work except for very junior folks who are proving the ability to string words together more than deep eng) * As mentioned, it’s a bit much of solo teams. Other small teams can comfortably communicate through issues (Jira) plus breakout sessions to hash out ideas. * Engineers also need to be onboarded to effective design doc writing. (note a top commenter frustrated that their first effort isn’t immediately met with adulation, a possible flag.) Writing about code is hard. Usually this is an exercise celebrated on HN. If you’re in a team, beware if you find your work is always that which doesn’t need to be explained and deeply considered in a shareable doc.
• deleted 2y ago
  [deleted]
• n3storm 2y ago
  Was a "design doc" what get IMAP killed at Gmail then?
  • staticfish 2y ago
    I'm not fully understanding your comment. What do you think is happening or has happened to IMAP at Gmail?
    • Macha 2y ago
      Don't know what the parent poster thinks, but what is happening is this: https://workspaceupdates.googleblog.com/2023/09/winding-down-google-sync-and-less-secure-apps-support.html https://workspaceupdates.googleblog.com/2023/09/winding-down... Which means that basically only apps that are approved by Google for OAuth can use IMAP in the near future.
      • staticfish 2y ago
        Interesting, thanks for the info. I must have missed this. It doesn't seem completely unfair to not pass your main Google password, and I imagine you still might be able to use generated application passwords if you really need the functionality (maybe).
        • Macha 2y ago
          The thing that is confusing here is you used to have to turn on less secure apps to use app passwords, and the article says that's getting removed for personal accounts. So while they don't say that they're removing IMAP via app passwords for personal accounts, there's a concern they might be effectively removing them it
          • staticfish 2y ago
            Interesting. I occasionally use this feature so will keep an eye on it. Thanks for the clarification.
• acatton 2y ago
  I do not share the same experience as the author, as someone working for the mentioned company. There is a wide range of types of design docs, and none of them are useful. I've rarely seen any useful design doc at Google. I feel that design docs are for engineers who are too much process-oriented. Here are the types of design docs I've encountered in the wild: * The promo design doc: it's not really explaining what this is trying to solve, it's more stating that this project is awesome, and makes the company better. The logical conclusion is that the author of this doc should be promoted. * The turbo-encabulator[1] design doc: this is a technobabble design doc which is full of terms never encountered before, and which is not understandable unless you're a senior member of the team. I'm sometimes not even sure the senior members of the team understand it... * The new-grad design doc: this a design doc with no substance, but as the person just graduated from university, they felt compelled to make is as long as possible, to prove... I don't know what... It is not conveying any information. They most likely copied/pasted huge chunks of the code they've already written, to fill most of the ~70 pages of the doc. * The made-up-facts design doc: this a design doc full of "everybody knows that", "they all say". Of course, it's not as obviously done as some politicians do it. But the design doc will push their design with "this follows good practices", "this software is slow, therefore..." who defined the good practice? why is it a good practice? what is slow? was it measured? is it an end user feeling? This is 99% of the design docs I've seen out there. Of course, exceptions exists, but they're very rare, in my experience. I'm shocked that the author pushes for this practice... But again, they were no engineer, they were a director, I guess design docs make sense for their position, for which I'm still trying to figure out the value these folks bring. [1] https://en.wikipedia.org/wiki/Turbo_encabulator https://en.wikipedia.org/wiki/Turbo_encabulator
  • mike_hearn 2y ago
    That must have changed. I worked there from 2006-2014, back then most design docs were useful and followed the basic structure described in the article (minus the system context diagram). I noticed early on though, that design docs maintained in Google Docs tended to be of lower quality than those maintained in the version control repository. Not sure if that was just a proxy for when they were written or whether the code review process is just more rigorous than editing things in Docs, but the only time I wrote a large (40 page-ish?) design doc I did it using hand written HTML and we worked through the code review system, as was traditional. I also posted it to the central mailing list and web server and got feedback from employee number 3, which was nice. The central location made it easy to find them as they were sorted by category. Still I don't recall design docs being important enough to matter for a promotion by themselves. Promos were supposed to be about overall impact, not production of specific artifacts. Of course the system was badly flawed, and often yielded surprising decisions in a bad way, but I don't remember ever reading an obviously-optimized-for-perf design doc back then. If you can find the website that holds the design docs hand written in HTML from the earlier years, try perusing some of those and see if you find them more useful (or would have done when the systems were contemporary). Some of them old ones like SmartASS were full of detailed explanations of the underlying equations and models, which was quite helpful for understanding how it worked, as well as the explanations of why those approaches were chosen. Reading those helped informed my own design work later. I wasn't a director, just an engineer, and they did help. There are also some Chrome design docs linked to from the chromium.org website that I found helpful in the past for understanding its design.
• iainmerrick 2y ago
  Documentation is good in general, but I think this approach is flawed: These are relatively informal documents that the primary author or authors of a software system or application create before they embark on the coding project. "Before they embark on the coding project". The design is the coding project, it's all the same thing. The idea that you can work out the design on paper before committing any code is just wrong. (The design doc approach in fact admits that you need to write some code up front, but tries to strictly compartmentalise it as "prototypes that show the implementability of the design".) A big feature of the up-front design doc is that it gives people license to nitpick, AKA review, before any serious coding starts. In my experience this usually means the doc gets extended by more and more caveats and discussions of pointless alternatives, and can become less of a "design doc" and more of a "please just let me start building this thing" doc. In cases where there are significant architectural problems that require a change in direction, they're better solved by talking to and collaborating with the right people in advance, rather than crafting a detailed design doc only to have it shot down. If you stick closer to the "relatively informal document" idea, and maintain the doc as you go, that can actually be useful, as it helps you produce useful documentation as well as a working system. But that's less "design doc" and more "write documentation as part of a continuous, collaborative process".
  • rockemsockem 2y ago
    If a project is sufficiently large and well thought out then architectural changes can be incorporated without too much extra work relative to the whole.
    • trelane 2y ago
      If
      • rockemsockem 2y ago
        No one is going to argue that poorly thought out design docs are a good thing. Like for docs to be useful they have to actually be good.
• ChrisArchitect 2y ago
  (2020) Some more discussion then: https://news.ycombinator.com/item?id=23915521 https://news.ycombinator.com/item?id=23915521
• deleted 2y ago
  [deleted]
• glimshe 2y ago
  If a big investor disguised himself and spent a few weeks as a Google engineer, they would quickly become an activist investor demanding Sundar's head. The magnitude of wasted human potential due to Google's design doc culture is almost incomprehensible.
  • esafak 2y ago
    Carl Icahn's the man for that. https://www.bloomberglinea.com/english/i-fired-12-floors-of-people-icahns-hostile-strategy-that-musk-could-emulate/ https://www.bloomberglinea.com/english/i-fired-12-floors-of-...
    • another2another 2y ago
      Quite amusing reading that article, then glancing over at the Social media links where of course Twitter is now replaced by that X (which, let's be honest is one of the quickest and most effective rebrands I can think of. Hats off to the X (formerly known as Twitter) team for doing that so slickly).
  • VirusNewbie 2y ago
    I think people are really over estimating how much effort goes into most design docs. Most development just happens and occasionally you slam out a doc to make it easier to justify CLs. Maybe one out of ten do I see someone who went way overboard but it is really not a time sink for the average SWE.
  • asdfman123 2y ago
    My theory is that late-stage Google is designed to hide monopolistic profits. This is exactly how I'd design a company if I wanted to burn as much money as possible.
• testfrequency 2y ago
  I once completed a six month project that had a 9 page design doc, and the required director never signed off - but the work had to start. The project shipped on time (successfully), but the director gave feedback on the design doc and asked for changes to the approach a day afterwards. Awkwardly, that director had no clue the project shipped the day prior without his input, and he held a special meeting with me to apologize for completely ignoring months of requests to review and approve the design doc. I hate design docs. I wasn’t even at Google, but worked somewhere that uses design doc culture. Thanks Google.
  • lantry 2y ago
    I don't see how design docs are the problem in your scenario
    • testfrequency 2y ago
      I don’t disagree. What I didn’t mention was that the project was delayed for weeks as I awaited sign off from the director. Getting a stale approval and request for revisions 6mo later after shipping only made me feel more so that design docs are just technical fluff pieces with no useful purpose beyond its origination.
• 3vidence 2y ago
  Another Googler here. Lots of good comments already describing the uselessness of design docs at Google. I wanted to add one additional perspective that I find problematic. As mentioned design docs are "promo" material which causes massive amounts of fluff. But they also seem to substitute actual documentation! Every design doc is out of date pretty much the minute they are finished but teams point to them instead of writing documentation. The result.... documentation at Google as pretty bad and out of date. Honestly I would've really preferred if documentation / instructions were promo material instead of writing 20 pages about what you DIDNT DO. Write 2 pages about how to use what actually exists
• datahack 2y ago
  A culture of design docs tends to push everyone into a justification layer for their work. Justification culture, even when it’s peer reinforced as culture, is a fairly repressive pattern to innovators. This system tends to prevent visionary efforts and aspirational projects because non-consensus focused efforts are quashed and thinking “outside of the accepted norm” means you’re going to be punished by the collective. This type of system breeds groupthink, and the tradition focused nature of “the way we do things” intrinsically enforces that doing anything else frequently becomes dangerous to your career. The valley has all manner of company cultures that rely on tropes wrapped in ‘agile’ and ‘design thinking’ verbiage that are primarily enshrined institutionalization masquerading as ‘the right way’ and usually comes with a healthy side dish of social enforcement of whatever ‘engineering cult culture’ variation that campus has arrived at. I can’t tell you the number of people I’ve met who left Google because it was limiting their career, even when they were deeply comfortable working there. It’s not a few.
  • ilrwbwrkhv 2y ago
    And that is why Google cannot build products at all. I just had a new pixel 7 fail on me yesterday. All of this pretend "we are very smart" behaviours are also a form of a bullshit job. Companies should focus and rate themselves on actual working products.
    • cmrdporcupine 2y ago
      Here's the thing though. Google builds the actually important products very well. Ads and Search. Particularly the former. The ad serving infrastructure at Google is huge and stable and makes insane money. Everything else is a sideshow. The real quality work being done at Google is by SREs -- not SWEs -- in Ads / Search & Core. The infrastructure they build and maintain is amazing and hard to explain to people outside. I say this as a former SWE there.
      • ilrwbwrkhv 2y ago
        Google search has been steadily deteriorating for over 5 years now and shows no sign of getting better, ads might be slightly better placed.
• yatz 2y ago
  Spot on, especially in large teams with a diverse set of skills.
• alienchow 2y ago
  The replies from Googlers in this thread surprise me. I've actually found DDs very useful for team onboarding, and for async stakeholder communications when making changes. Design docs typically also lead to fantastic g3doc documentation. It's a much better experience than having to fish around the team to piece together fragments of tribal knowledge about design choices for a system.
• methods21 2y ago
  How about some actual examples?
• larsrc 2y ago
  Googler here. I used to hate writing design docs, even though I have several published papers. But a few years back I realized the main benefits for me: * It empties my head of the immediate parts of the idea, letting me move on to deeper parts and more productive considerations. * It makes flaws more obvious, especially to myself. * It makes it easier to share these thoughts, especially with people in other offices. They usually give really good feedback. * It gives me a much better idea of how much work is involved than if I just start coding. * It usually points out some things I need to learn before I start coding - adjacent systems, appropriate tech choices, etc. Yes, it's also good for promo, but a successful project is better. I often get comments on how useful my docs are, so I think I'm onto something.
  • ZainRiz 2y ago
    Same here. I found the biggest beneficiary of a design doc was my own thinking process (Xoogler here)
• larsrc 2y ago
  Design docs are the _mise en place_ of software development.
• ein0p 2y ago
  I feel like people would miss the forest for the trees here. Google design docs are nothing special. The special part is hard to replicate elsewhere: the reviews and the thoughtful comments they often receive that prevent a lot of wastage of time and resources, and the way these comments are selectively incorporated by the authors. That comes from knowing shit and giving a shit, the latter quality being in short supply as of late industry wide, including at Google.
• ZainRiz 2y ago
  Google has the concept of a mini-design doc called a "One-pager" In 2018, the template for this "One-pager" was two pages long
• djmips 2y ago
  "A clear indicator that a doc might not be necessary are design docs that are really implementation manuals." Where I work - this is what they want from a design doc. They want it to be such that you could hand it off to anyone and they could implement it. What does HN think about that?
• youngtaff 2y ago
  Would love to have seen the design doc for AMP…