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.
You get the behavior you incentivize. In the “early days”, design docs were a tool to agree on a direction and provide context to your coworkers about what you’re doing. Later, as new people joined at an exponential rate, they were told by well meaning managers to write the docs for perf reasons, and things kind of spiraled from there. Google’s culture became a cargo cult of itself.
Some companies I worked at after Google were reluctant to discuss their promotion process in detail, because they saw what happens when people microoptimize for it.
When I was at Google I mentored a lot of early career engineers and I always told them to write more docs than they think they need. Sometimes docs will catch problems beforehand but early in the career writing easy docs is a simple way to show independence and competence. It slows down projects but Google is probably gonna cancel that project anyway and my theory was "Google doesn't care about you so caring about it just makes you a chump". It was in most ways a great place to work but it slowly drove me insane.
This is likely due to culture established by the teams working on old, mature products. There, you're going to work with at least 10 people to launch trivial projects. In my case, it's usually 20~30 people with a blast radius of 100~500. You're not going to casually 1:1 with all of them since you and they are all busy. If you don't get a good review from stakeholders, there's a good chance that some angry folks will come for you and make you roll back your launch.
In these contexts, design docs are meant as an asynchronous communication tool for information heavy topics. And this is so asynchronous, you will talk to those people join 10 years later if you product becomes so successful. I've been saved multiple times thanks to some random design doc from 2010 that explains the weird decision that still haunts us. This probably doesn't work very well on lean/small teams or less complex tasks. But engineering culture usually has its own rationale and context, even if it has become a cargo culture.
We do "one-pagers" if there's basically one, simple, straight forward way to do something; however, I'm with google on this one.
If you're designing something, and there's only a single solution under consideration, either there's no design, or you're not being thorough. Choices and tradeoffs are what make design
What if it is something really obvious and has been done so for last 20/20 times it feels almost embarrassing to consider anything else? You could list out the embarrassing methods, but it still feels useless work for show.
I have a reverse problem at the place I work. When I ask people to write a very high level design doc for a fairly trivial task they go - "There many more way to get this done so writing these is useless. And as the task is trivial an engineer should be able to figure out one of these ways and do it."
Many of these people are external consultants who have been working with the company for 15+yrs. So, there is a fair standard in place already because the tasks are done by the same people. But then they go out of their way trying to create a boogeyman of "what happens if people don't follow the standards?".
The end result is that either design docs don't exist or woefully out of date. Hence the company has to keep hiring these same consultants year after year on hugely inflated costs.
Used to feel this way on other teams. Almost as if you were expected to write them for the sake of writing them (cargo cult engineering).
Now on a team of many OG Googlers (15+ years tenure) and Design Docs only exist when they’re needed (something that touches multiple systems, something that’s obviously complicated with many trade offs, etc) Otherwise it’s just “write the CLS.”
> Now on a team of many OG Googlers (15+ years tenure) and Design Docs only exist when they’re needed
This almost certainly has nothing to do with the team or tenure, but everything to do with what levels they are(n't) trying to get promoted to. Have you controlled for that and still seen a distinction?
This isn't unique to Google. This is encouraged at Uber and Airbnb as well. I would think its a common practice. The idea is to show that you consider alternatives and did due diligence. Following the way its always been done isn't necessarily a good thing. If its a different product area there could be better approaches unique to that area. Its not fake work, it just proves you actually considered other approaches instead of blindly following status quo.
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.
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.
> You have a point in that bureaucracy can needlessly get in the way of meaningful change.
What a good early design doc can do is turn meaningless changes (e.g., doing a project for the sake of promo) into meaningful non- or minimal change. The best code is the one not written.
And at least in my area (Core), the design docs only go through anything like a formal process when it's a larger project that would take years or multiple engineers. Other areas are probably different.
Then include templates from other areas pointing out the repeated work. You can’t just hand off a couple of lines in a brief to a dev, especially if they are not aware it’s been done before.
The mistake was production of a design doc instead of just writing the code. If it's trivial enough that there's nothing to discuss, you generally just change the code. If it's complicated enough, it becomes a negotiation process where at least 5 different people have to be able to put it into their perf if you want to get it done.
the compensation structure in big tech makes people lose their minds optimizing for that next promotion/stock grant. It helps big tech retain talented people but the incentives to look "impactful" drive all the wrong behaviors
The old school way of fixing that problem is to have a standing change order for routine work so you can point to it and say "my problem is just like that" and get the green tick right away. Though the moment you suggests things like change control people get all weird these days.
> The decision whether to write a design doc comes down to the core trade-off of deciding whether the benefits in organizational consensus around design, documentation, senior review, etc. outweigh the extra work of creating the doc
I'd argue that extra work of creating the doc is an upside because it clarifies your thought process, and design-by-committee is a massive downside.
In fact, I happen to be writing this during a design-doc meeting. I am getting absolutely nothing from it. I was writing code all morning and the background noise now prevents me from continuing productive work.
The problem with stuff like this is that it saps the (finite) energy of your team. Not everyone is a tank. High int lose their hit points and they're gone with all their mana.
I'm dealing with this right now at another large company. Being asked to write a document for an integration we've done 20+ times because its part of someone else's larger promo project's design.
I interviewed a couple of folks from Google recently and it was mindblowing how they "work", it's very unfortunate. I feel for some of the people who only worked there their whole lives (e.g: from recent grad within the last 5y), it is unlikely that they actually know how to program.
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.
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 :)
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.
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.
> 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.
The worst case is really when even more time has been spent coding, testing, releasing, and integrating the overly complex design, and then it's extra work on top to get rid of it.
> 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.
I do that at Google regularly, often in parallel with writing the doc. Nothing beats talking with an experienced engineer directly.
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.
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.
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.
> 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.
How can you prove "impact" to a committee who otherwise doesn't know your work, without providing evidence in the form of docs, code examples, and other artifacts?
I've seen design docs work when you have a relatively high number of junior roles compared to seniors. It forces the junior developers to think through their solutions ahead of time and justify their decisions, and it also allows senior developers to validate those decisions and give feedback asynchronously.
Granted, I've never worked in an org with more than 30-40 engineers, as I've always worked in startups. I'm sure things are different in big tech, but I've had positive experiences with them.
Need time and effort to ensure junior docs are thorough. Usually multiple revision in my experience. This require acceptance from management that "just write code fast" is not a success path.
IMO the uses for a technical document (design doc or a shorter doc) is simple. If you get to the point where you can't hold every single detail about a project in your head at once then you should write a doc. Similarly, if it will take a long time (30 minutes at least) to explain to another engineer, you write a doc, to save yourself time.
IDK how you can think that you never need to write a document
My experience has been that the second one means, "I need to communicate with my team/TL what I'm doing/how I'm solving this problem." Eventually, when you go for promotion, you take documents in category 2, and add enough context to them that they become category one.
It sounds like there's no good review process for these; if they lack substance or are too long, they should never be published. But I take it that the people responsible for the people writing these also get the benefits?
There is a review process, but "yes, your comments are relevant, but they're just nit picking, can you just approve it so that we can start working on this project?"
It feels like this case where when people are reviewing each other they might feel incentivised to be easy on each other in agreement so that both would get the promo easier, especially if they both think the doc is just for show to get the promo.
Am I going to be a difficult person here finding each and single flaw about the doc or should I just allow it, let the other person get more visibility and just move on with my work. Why should I be a bottleneck here for a pointless battle.
The promo design doc is directly incentivized by managers: “if you just see a bunch of CLs, it doesn’t tell a story. You need to write it down as a coherent narrative and get some >L5s to comment on it”. “It’s not for me it’s for the committee - they aren’t familiar with your work so you need to explain it”.
> But again, they were no engineer, they were a director, I guess design docs make sense for their position
Yeah I think it’s just high potency ammunition in the middle management[1] turf wars. Not even product managers care much about DDs.
[1]: Liberal definition: anyone who uses the word “cross-functional” colloquially, independent of their actual job title.
> There is a wide range of types of design docs, and none of them are useful.
I write them mainly as a tool to get visibility with superiors. I try to make them as fancy as possible to to make them think i am "leadership material". I've been feeding them to chatgpt to rewrite them in fancy language.
Red rag to a bull: "this is best practice". Really? There is no better way to do something given more context or experience? A better practice will never be discovered or devised?
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".
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.
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.
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.
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.
What makes them valuable or not valuable is how people respond to them. If it is all done as a "ritual" then it is stupid. If it is done because the org is legitimately critical about how it makes decisions and prioritizes resources, then it is valuable.
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.)
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.
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.
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).
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.
"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."
This is why they pay so high. It's a trap. That, and the apparent "status" of working there (which has mostly worn off now)
You've expressed my frustration with what I experienced there exactly. But I do wish I could have that pay back...
Also re: "agile" I came into "agile" 20ish years ago in the form of eXtreme Programming, and it looked nothing like the cargo cult that is SCRUM or its imitations today. It was, in the end, a set of precepts to put creative power into the hands of developers and let them just get things done without management getting in the way of how -- but in exchange the customer is given the ability to say what things get done and (to some degree) when. Developers do their own estimates. "You ain't gonna need it". No big "upfront design". Refactoring and testing, architecture and design built in as a constant overhead as just standard best practices, not stories or tasks in themselves. Planning meetings are coworkers hashing things out in a room, and "stories" are sticky notes on a whiteboard expressed in minimal, non-technical terms. Standups are literally people in a circle giving a very brief update, in case anybody else is interested, not a ritual to prove you're attending work today, or to show off.
In this system, design is an emergent property of a creative group of experts working together. It doesn't preclude design documents, and it still involves architecture discussions. But it doesn't require an explicit PRD/design-doc process.
How I'd like to work in a shop like that again. I can tell you Google was the polar opposite. Everything took forever.
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.
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.
Readit News
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.
Some companies I worked at after Google were reluctant to discuss their promotion process in detail, because they saw what happens when people microoptimize for it.
Deleted Comment
In these contexts, design docs are meant as an asynchronous communication tool for information heavy topics. And this is so asynchronous, you will talk to those people join 10 years later if you product becomes so successful. I've been saved multiple times thanks to some random design doc from 2010 that explains the weird decision that still haunts us. This probably doesn't work very well on lean/small teams or less complex tasks. But engineering culture usually has its own rationale and context, even if it has become a cargo culture.
If you're designing something, and there's only a single solution under consideration, either there's no design, or you're not being thorough. Choices and tradeoffs are what make design
Dead Comment
Many of these people are external consultants who have been working with the company for 15+yrs. So, there is a fair standard in place already because the tasks are done by the same people. But then they go out of their way trying to create a boogeyman of "what happens if people don't follow the standards?".
The end result is that either design docs don't exist or woefully out of date. Hence the company has to keep hiring these same consultants year after year on hugely inflated costs.
There it is. There's good scratch to be made in prolonging the problem.
Now on a team of many OG Googlers (15+ years tenure) and Design Docs only exist when they’re needed (something that touches multiple systems, something that’s obviously complicated with many trade offs, etc) Otherwise it’s just “write the CLS.”
This almost certainly has nothing to do with the team or tenure, but everything to do with what levels they are(n't) trying to get promoted to. Have you controlled for that and still seen a distinction?
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.
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.
What a good early design doc can do is turn meaningless changes (e.g., doing a project for the sake of promo) into meaningful non- or minimal change. The best code is the one not written.
And at least in my area (Core), the design docs only go through anything like a formal process when it's a larger project that would take years or multiple engineers. Other areas are probably different.
> The decision whether to write a design doc comes down to the core trade-off of deciding whether the benefits in organizational consensus around design, documentation, senior review, etc. outweigh the extra work of creating the doc
I'd argue that extra work of creating the doc is an upside because it clarifies your thought process, and design-by-committee is a massive downside.
In fact, I happen to be writing this during a design-doc meeting. I am getting absolutely nothing from it. I was writing code all morning and the background noise now prevents me from continuing productive work.
Deleted Comment
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.
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.
The worst case is really when even more time has been spent coding, testing, releasing, and integrating the overly complex design, and then it's extra work on top to get rid of it.
> 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.
I do that at Google regularly, often in parallel with writing the doc. Nothing beats talking with an experienced engineer directly.
I long for design docs that are worth more than their cost.
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.
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
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.
How can you prove "impact" to a committee who otherwise doesn't know your work, without providing evidence in the form of docs, code examples, and other artifacts?
Granted, I've never worked in an org with more than 30-40 engineers, as I've always worked in startups. I'm sure things are different in big tech, but I've had positive experiences with them.
IDK how you can think that you never need to write a document
Am I going to be a difficult person here finding each and single flaw about the doc or should I just allow it, let the other person get more visibility and just move on with my work. Why should I be a bottleneck here for a pointless battle.
The promo design doc is directly incentivized by managers: “if you just see a bunch of CLs, it doesn’t tell a story. You need to write it down as a coherent narrative and get some >L5s to comment on it”. “It’s not for me it’s for the committee - they aren’t familiar with your work so you need to explain it”.
> But again, they were no engineer, they were a director, I guess design docs make sense for their position
Yeah I think it’s just high potency ammunition in the middle management[1] turf wars. Not even product managers care much about DDs.
[1]: Liberal definition: anyone who uses the word “cross-functional” colloquially, independent of their actual job title.
I write them mainly as a tool to get visibility with superiors. I try to make them as fancy as possible to to make them think i am "leadership material". I've been feeding them to chatgpt to rewrite them in fancy language.
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".
* 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.
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.
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.
(disclaimer: very org dependent, as all statements about Amazon are.)
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.
This is exactly how I'd design a company if I wanted to burn as much money as possible.
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.
This is why they pay so high. It's a trap. That, and the apparent "status" of working there (which has mostly worn off now)
You've expressed my frustration with what I experienced there exactly. But I do wish I could have that pay back...
Also re: "agile" I came into "agile" 20ish years ago in the form of eXtreme Programming, and it looked nothing like the cargo cult that is SCRUM or its imitations today. It was, in the end, a set of precepts to put creative power into the hands of developers and let them just get things done without management getting in the way of how -- but in exchange the customer is given the ability to say what things get done and (to some degree) when. Developers do their own estimates. "You ain't gonna need it". No big "upfront design". Refactoring and testing, architecture and design built in as a constant overhead as just standard best practices, not stories or tasks in themselves. Planning meetings are coworkers hashing things out in a room, and "stories" are sticky notes on a whiteboard expressed in minimal, non-technical terms. Standups are literally people in a circle giving a very brief update, in case anybody else is interested, not a ritual to prove you're attending work today, or to show off.
In this system, design is an emergent property of a creative group of experts working together. It doesn't preclude design documents, and it still involves architecture discussions. But it doesn't require an explicit PRD/design-doc process.
How I'd like to work in a shop like that again. I can tell you Google was the polar opposite. Everything took forever.
Ah, ah, ah. This is why they pay so high so far.
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.