return to table of content

Design docs at Google (2020)

SSchick
73 replies
1d11h

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.

t8sr
29 replies
1d10h

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.

Arainach
19 replies
1d6h

Microoptimizing for what the cargo cult believes gets you promoted is strictly worse than microoptimizing for what actually gets you promoted.

JustLurking2022
11 replies
1d5h

At some point, the cargo cult are the promo reviewers and then the two become the same thing.

Arainach
10 replies
1d4h

The reviewers presumable have access to the true metrics.

trelane
7 replies
1d4h

What if I told you these are their "true metrics?"

Arainach
6 replies
1d4h

If a company doesn't have consistent metrics for performance reviews uniformly across teams, get out of that company yesterday. That's just a hotbed of nepotism.

lupire
5 replies
1d3h

Please give an example of a metric for performance review for software engineering.

Arainach
4 replies
1d2h

Conceptual examples (not looking to argue about the specific bar):

Senior engineers will:

* Design a significant project which lands with measurable customer impact

* Demonstrate expertise in at least one core skill outside of coding (test infrastructure, SRE, security, accessibility, etc.)

* Demonstrate leadership by either being a TL, owning and leading team pillar efforts (security review, etc.), etc.

* etc.

Mid-level engineers will:

* Own either a small feature end to end or a significant piece of a larger design

* Contribute to at least one non-coding pillar

* etc.

These generally have more areas and can be further granular such as "low-performing midlevel is X, satisfactory is Y, exceeding is Z"

dpe82
3 replies
1d

Those are requirements, not metrics.

tra3
1 replies
15h40m

Agreed.

Just proves the point, this person just cargo culted what makes google so famous in recent years. If you only metric is to launch new projects, you’re only gonna launch new projects. Who’s gonna get promoted for maintenance.

Arainach
0 replies
8h39m

Conceptual examples (not looking to argue about the specific bar)

Again, not trying to debate what the specific bar should be, just giving examples of the kind of metrics you can use. What's your preferred alternative? Lines of code? Whenever your boss feels like it? Stuff like that is why no one believes a "senior staff superstar" from the hot startup of the week is any good and requires them to do whiteboarding.

Arainach
0 replies
21h45m

With sufficient granularity there is no difference. I can't give exact quotes without violating NDAs but variations on these have been the performance review standard at every major company I've worked at or known people who work at.

mewpmewp2
1 replies
1d4h

What do you mean by "true metrics"?

Arainach
0 replies
1d3h

The metrics which determine if someone gets promoted. Those decisions are being made by some group, presumably with guidelines. If the process for getting promoted is "this group does whatever they feel like" that company is a disaster and you need to get out.

Thus, there are rules, and they are written down. If they're not visible to normal employees, they guess the rules based on who they see get promoted (cargo cult) while the committee uses the true metrics.

It's not like becoming a manager is a secret cult where you're dropped in and you suddenly have carte blanche to do anything. At established companies there are rules and procedures, and while you will likely have access to more information than individual contributors, you won't just be promoting whoever you feel like without having to go through others.

klabb3
5 replies
1d5h

It’s a meh from me - either is bad. If you are in a highly complex and professional field (in the traditional sense of the word) single axis optimization hollows out the whole craft. Engineering is delicate and constant battling of tradeoffs, and decision consequences are often delayed by longer than average tenure, let alone a 6 month perf cycle. The more you McKinsey the process, the more mediocre and incoherent the results.

Arainach
4 replies
1d4h

You get what you measure. You can't hire smart motivated people and then be surprised when they figure out to optimize for their rewards.

If you want a team that lands stable customer-loved products, make THAT your performance review. Turns out that's hard to do objectively and consistently.

lupire
2 replies
1d3h

According to your other comment, then, a company that "lands stable customer-loved products" would be a "hotbed of nepotism" that people shouldn't work for.

Arainach
1 replies
1d1h

Nonsense - you can have documented metrics which are known and tied to performance.

For example:

* Require features to be launched for a period of time rather than in development or shoved out the door a week before perf

* Have metrics for customer satisfaction and oncall pages be incorporated

Etc.

aprdm
0 replies
20h19m

Nonsense were a lot of your replies in my experience :), this "measure everything" is very much another cargo cult. Software engineering is complex, people are complex, thinking you can come with a true metric and who doesn't have it doesn't know what they're doing is the nonsense in my world view.

Have excited engineers, pay them well, have them work on something that is aligned with their career & deliver value to their customers, they don't really need much more than that. All the rest is simply trying to "processi-ze" what is a human

klabb3
0 replies
1d3h

You can't hire smart motivated people and then be surprised when they figure out to optimize for their rewards.

Never said that. I don’t have a solution. Well I have a partial solution, but not complete:

Reward all team members equally for the performance of the team, or even the company. For instance: the pie is divided into 3 pieces: company, team, and individual performance. Candy is given out based on performance of both.

It doesn’t fix the hackable metrics issue, but when people collaborate the side effects are better than when they think of their own promotions, and worse when they’re competing against their direct peers for a fixed bucket of candy per team. Such incentives are directly opposing collaboration between the very people that need to collaborate the most.

racional
0 replies
1d3h

Either way -- 'twould seem that if such a level of microstrategizing is what monopolizes one's attention on a day-to-day basis -- then one is definitely in the wrong place.

tdb7893
8 replies
1d4h

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.

mewpmewp2
4 replies
1d4h

But if they are going to cancel it anyway I would rather at least code and build just to have fun and at least have a prototype rather than doing the boring work. Also I feel like I can't get into right frame of mind of problem solving by writing a doc compared to if I am coding.

rvnx
2 replies
1d4h

If the project is anyway eventually going to be deprecated and shutdown, maybe it's better to take one of the Google bike and go round the campus drinking one of these tasty granitas from the cafeteria.

tdb7893
0 replies
1d2h

The craziest thing to me is that at my location not that many people did the free workout classes. Between those classes and the food I was in the best shape of my life while working there.

I steadily got in better shape as they kept cancelling the projects I worked on and I slowly lost and sort of will to care about my actual job. The quality of my work ended up suffering a lot as I realized just how pointless trying to work there was for me but the pay was too good to want to leave.

Edit: I was unlucky though. I knew some people with more stable projects. I went through 4 cancelled projects in close to 6 years

mewpmewp2
0 replies
1d3h

Is there alcohol in it? If so, I would consider, but I would still take the alcohol and code the project as well.

tdb7893
0 replies
1d2h

If they like coding and didn't want to prioritize career advancement I would tell them to put effort into finding the projects (or parts of projects) they find more interesting to code and make sure they get assigned that. My advice was always personalized. The thing is that for most early career engineers they are already coding enough (and it's not like the code is generally particularly interesting) so most of the time the advice is to do more docs since the lack of docs was hurting them for perf/grad but it varied from individual to individual

scottyah
2 replies
1d2h

This sounds like you are championing the very mindset that has made google crumble?

Write docs that slow things down, don't code/build projects, and do it all in the name of greed and the only justification is that it will get cancelled anyways (probably because no real work was being completed).

tdb7893
0 replies
1d2h

I was just a cog in a machine. The mindset didn't come from me but how they setup incentives internally and ran projects. To be clear, I ended up really resenting how it works and the advice was based on my experiences with trying to care (in fact I'm trying to get out of tech entirely). I ended up channeling my care and effort into building up coworkers rather than into the company or it's products and that's how I got through it for a while. Different people had different experiences though (it's a huge company after all), anything I say about my experience is very personal.

Edit: also if Google wanted me to really care about my job more than for self interest that relationship needed to be a two way street. The relationship of the devoted employee and disinterested company is common but to me comes across as a bit pathetic. I did a good job there purely because that's how I enjoy doing my job, if the company collapsed I wouldn't have shed a single tear (that's a lie, I miss the free food)

larsrc
0 replies
1d2h

Caveat: Googler here.

One of the things that had been problematic at Google is the creation of many more products than are really needed, leading to the infamous Google Graveyard. One of the reasons I have come to like writing design docs for my ideas is that a lot of the ideas turn out to be crap when they get written out. Quite a few are good enough that they have already been done, or close enough, which my colleagues can then inform me of. This is a very lightweight way of trimming out useless projects.

And no, Reader wasn't useless. Different story.

jppittma
17 replies
1d8h

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

mewpmewp2
16 replies
1d6h

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.

masto
7 replies
1d4h

I don't want to get sucked into defending Google-style design docs (I have.. opinions), but on this particular point a couple of things come to mind:

1. Presumably you've written the doc to be read by other people. What's obvious to you might not be obvious to them.

2. If you have no "alternatives considered", it's an indicator that you didn't consider any alternatives. I can think of times when "this is obvious and it's the way we've always done it" sent me down the wrong path. Spending just a couple of minutes considering whether obvious == correct, and writing down why, is not a bad investment in the long term.

3. I can only speak for myself, but I don't enjoy being criticized and I don't enjoy being wrong. "Alternatives Considered" is often at the end of the doc and I'm tempted to avoid it because there's a very real possibility that I will find the process of explaining why we don't just do option B instead leads to a realization that option B is a better alternative than the plan I just spent all that time on.

9/10 times it's short and easy, but it's still a worthwhile exercise for the reasons above. Explaining the "don't do anything" alternative is a good way to reinforce the cost/benefit of what you're proposing, and it's usually pretty easy to put yourself in someone else's shoes for a second and think of the first "but why don't you just" that will probably pop into their head. Write down "because it won't scale" and you've saved yourself that conversation. (joking. maybe.)

aatd86
6 replies
1d3h

I can only speak for myself, but I don't enjoy being criticized and I don't enjoy being wrong.

That's actually a huge problem because it can veer onto intellectual dishonesty and being combative for nothing. Instead, one should be trying to look for the right/best path forward, regardless of what they thought. Should be easy to discard erroneous ideas.

The goal is not to be right. It's to find what's right.

goostavos
3 replies
1d2h

The goal is not to be right. It's to find what's right.

This is why I think design docs need to be lightweight and reviewed early. Design docs shouldn't be a masterpiece perfected in isolation over the course of days or weeks. That guarantees the author has calcified their opinions. When I was on review panels at Amazon, 99% of them were an exercise in futility -- the author had already poured concrete. It is very, very, very hard to avoid the mental trap of "Hrmph! I've thought about this more deeply than anyone else" that comes from living down in the isolated world of "doing design."

The earlier you get other eyes involved, the more likely people will actually listen to feedback and consider alternatives. You still, of course, need that heads down time to put in all the details, but the overall shape of the design shouldn't be a big reveal when you hit the design review.

pfannkuchen
1 replies
21h45m

I think there is a risk of going too far in the other direction leading to design by committee. It’s often the case IME that a casual reader actually hasn’t thought through the problem enough to understand why their drive by feedback or alternative doesn’t make sense. A process that results in those things getting accepted may just be introducing more entropy into the design process.

aatd86
0 replies
21h27m

Good comment. I think both of your perspectives are fair and manifest in the size of what is being designed.

Meaning that if someone designs something huge, end-to-end, it's going to be difficult for external people to address potential flaws within the design. A lot of interlinked parts requiring to have the full mental model loaded in the brain. So one should go step by step.

It's also true that not every feedback is equal and it's important to think in advance about how to address rebuttals since most people don't give in-depth feedbacks but surface gut feeling (which can be invaluable too, even if simply in terms of UX), unless they have wondered about how to solve the same exact problem before. That requires more time spent thinking about the design.

eschneider
0 replies
22h41m

So much this. Bouncing early design ideas (informally) off other stakeholders or at least more experienced engineers can save SO much pain. The reverse of that is true, too: giving early feedback on other people's designs can give them the insights THEY need not to inflict pain on YOU.

imissmymind
1 replies
1d2h

I had a wise friend tell me that engineers are always in a state of being wrong. What you build today you will most likely laugh at in five years. The goal for today is to build the least wrong thing you can. I used to argue more than I should have simply because I didn't like being wrong either. After hearing this, it helped me to become more objective.

aeonik
0 replies
17h38m

My problem is that the least wrong thing I know of is very different from all existing processes, and take more time and money than most are willing to stomach.

Jensson
4 replies
1d6h

Then it is just a change and reviewed through normal code review. Design docs is only for when you do something that isn't obvious.

mewpmewp2
3 replies
1d6h

But then you don't get promo?

Arainach
1 replies
1d6h

You don't get promo in your scenario either. A design doc for something that's trivial will be called out in promo packet review and not given much credence. If the packet is primarily comprised of such artifacts the promo will be denied.

lupire
0 replies
1d3h

It depends on level. For a junior, these are great design docs because they educate other juniors about engineering, and educate senior bad-doccers about good doc writing, and show developing skill in the art of doc writing, before the engineer has the additional cognitive burden of writing about something much harder.

jppittma
0 replies
21h8m

Do good non-doc-worthy work => Get doc-worthy work => Write doc => Get promo

eschneider
1 replies
22h47m

Hmm...most of the time when I do a design that's for something at all substantial, I'll usually go through a few ideas that seem reasonable at least through the "napkin stage" before dumping them in favor of what eventually becomes the "real design". I'd just save those napkins, list them in the alternatives section, and explain why they were abandoned. Easy.

jppittma
0 replies
20h18m

That’s the idea. I try set it up so the time I spend on the idea in the doc is proportional to its viability.

burnished
0 replies
1d3h

Then it'll be easy and fast and really not embarrassing at all.

devjab
6 replies
1d11h

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
3 replies
1d11h

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.

devjab
0 replies
1d5h

Oh I’m not a big fan of it either. Especially because I’ve never really seen a lot of the “fake work” have much value. Usually enterprise architecture or whatever you want to call it ends up being an insane amount of aged documentation that is useless because it’s never updated despite the best intentions. Over the years it’ll typically also erode its own standards as the people leading the efforts change and their standard preferences change with them.

Last but not least, it’s a total waste of time to have actual developers do it. Instead of working on something useful. Of course the challenge then becomes that 90% of the architects and whatever actually don’t know how to write their own design documents from changes, which means they need to waste developer time to do it… meaning that no only are they a completely useless employee they are also wasting the time of useless employees.

This shouldn’t be taken as black and white. As I wrote earlier, it can be done to help work flow. It’s just than in reality these processes usually end up doing far more harm than good. But if you, are, going to do it, at least enforcing standard is the right thing to do.

I personally avoid working at places with too much bureaucracy because I don’t want to waste my time writing documents nobody will ever read after they are approved.

Lutger
0 replies
1d8h

Good work needs to look good in order to be seen. And in enterprise, it needs to be able to be compared in order to be fair and afford some level of control from top down.

Standards solve those problems at the cost of some overhead and waste, due to being what they are: a fairly generic reification of best practice (at best).

Even though some overhead is just inherently part of the game, the efficacy of standards (and metrics) does vary. Not all have equal merit. And it does sound like some of the Google standards went off the rails a bit.

Degorath
0 replies
1d8h

Sad to hear your team was like that, mine definitely went the way of "if you know which way you're going to solve a problem anyway, why bother writing a design doc?" and I never felt burdened by them.

larsrc
0 replies
1d1h

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.

kortilla
0 replies
1d10h

What you said would make sense if they weren’t forcing the author to go find more alternative approaches.

brotchie
4 replies
1d4h

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.”

andrekandre
1 replies
1d3h

  > Otherwise it’s just “write the CLS.
(apologies for the noob question) but what is cls in this instance?

lupire
0 replies
1d3h

Change Lists (Pull Requests, Change Sets)

lupire
0 replies
1d3h

One presumes in those simple CL cases, there is already a doc for the system being edited, and the new code followes the design.

dataflow
0 replies
1d2h

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?

thisisit
1 replies
1d9h

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.

Cthulhu_
0 replies
1d8h

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.

weezin
0 replies
1d4h

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.

summerlight
0 replies
1d1h

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.

rexreed
0 replies
21h16m

Another word for Design Doc = "Shelfware"

pclmulqdq
0 replies
1d5h

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.

menzoic
0 replies
20h5m

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.

m463
0 replies
11h40m

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.

jvans
0 replies
1d6h

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

iimblack
0 replies
20h28m

Couldn’t you just reference a recent doc and say this is mostly the same with these x differences leading to y alterations for z reasons?

gonzo41
0 replies
1d11h

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.

dyauspitr
0 replies
1d10h

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.

aprdm
0 replies
20h14m

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.

acatton
18 replies
1d9h

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

mike_hearn
4 replies
1d9h

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.

ryandrake
3 replies
1d2h

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?

mike_hearn
2 replies
1d2h

Traffic, revenue.

okdood64
1 replies
20h20m

That leaves out a lot of work that folks do that don’t affect either of those directly.

mike_hearn
0 replies
10h23m

Yes the most common complaint about any incentive system that rewards "impact" is that it's hard to demonstrate for some kinds of jobs. I started in SRE ("devops") and then later moved to anti spam and security, so had to find alternate ways to demonstrate impact.

Still, the intuition is obvious enough. If you don't tie incentives to some sort of verifiable impact on the business then a lot of people end up doing make-work in which the appearance of doing work substitutes for actually being useful. As this wider thread is complaining about, in fact.

A common form of this complaint can be found in any business that makes software, that refactoring or "tech debt" style work is hard to justify via business oriented metrics. There's some truth to that, but also I came to feel that forcing people to find some sort of business-related metric they're affecting helps keep engineers honest. When to take on and when to pay down tech debt is one of the most nuanced and difficult subjects for any engineer to learn on their path to seniority, and becoming obsessed with refactoring is one of the most common failure modes along the way. Saying "but how did this actually affect the business" forces a reality check that can help avoid doomed rewrites and other pathologies.

For example, Google has a system that automatically finds and deletes dead code. This is the sort of thing that at first seems hard to justify, but with a bit of work you can do it. Work out the overall eng cost of maintaining each line of code (some napkin calculations are fine), work out how much code you're able to delete, work out the cost of developing the auto-deleter system, show that money spent on maintenance of dead code > cost of developing the system. Business impact demonstrated, done.

It doesn't have to be monetary either. I never demonstrated monetary impact. It was all things like "contributed to the launch of X that increased traffic by Y". In the case of the security and antispam work it was "successfully blocked Z attacks against our users", stuff like that. The impact is obvious even if not expressed in dollar terms.

apwell23
2 replies
1d7h

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.

darkwater
1 replies
1d5h

If you are a googler, you should be using Bard.

apwell23
0 replies
1d4h

i am trying to get promoted not fired

Cthulhu_
2 replies
1d8h

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?

mewpmewp2
0 replies
1d6h

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.

acatton
0 replies
1d7h

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?"

danielvaughn
1 replies
1d5h

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.

alwaysbeconsing
0 replies
1d1h

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.

rockemsockem
0 replies
1d3h

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

klabb3
0 replies
1d5h

Spot on haha.

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.

jppittma
0 replies
1d8h

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.

iainmerrick
0 replies
1d8h

Yes! Although I think you forgot one, the "please just let me start coding" doc.

alexchamberlain
0 replies
23h30m

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?

billfruit
10 replies
1d11h

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.

iainmerrick
4 replies
1d8h

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/...

- 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/...)

- 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?"

pjmorris
1 replies
1d5h

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.

Shades of Parnas! [0]

[0] 'A Rational Design Process: How and Why to Fake It', Parnas, Clements, https://users.ece.utexas.edu/~perry/education/SE-Intro/fakei...

iainmerrick
0 replies
17h49m

Huh, I don’t recall reading this paper before, but it’s terrific! I hadn’t previously seen it laid out as clearly as this, but yes, “faking” the design doc is exactly what happens in practice, and it’s a good thing! Since we want design docs that are useful now, not just obsolete historical artifacts.

jppittma
1 replies
1d7h

Google is a huge company with ~180,000 employees. Sometimes people do sensible things.

iainmerrick
0 replies
1d6h

Well, sure! They have many thousands of really smart developers.

I don’t think this particular doc, although it is a really good doc, supports the design doc process as described in the original article. It looks like good work being done in spite of the process, not because of it. It’s obviously just one data point, but I’d put it down as a negative point.

I wonder if anyone has done a proper investigation into whether the process is a good one?

swah
0 replies
1d4h

I guess in the open source side we would talk about Github projects with the greatest READMEs...

rullelito
0 replies
1d11h

Companies keeping their IP a secret? Weird..

yareal
8 replies
1d13h

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
7 replies
1d12h

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
2 replies
1d12h

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
1 replies
1d11h

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
0 replies
1d9h

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.

faizshah
1 replies
1d11h

This highly depends on team and project. The more ambiguous your project is the more likely no decision will be made and you will instead need to commit to a follow-up meeting with more docs and more people.

dbish
0 replies
1d9h

Yes the design by committee will continue until morale improves.

underdeserver
0 replies
1d12h

That wasn't my experience at Google. We would consistently start work in parallel to getting our design docs reviewed, maybe waiting a day or two for the first batch of comments.

You could usually tell which parts are not going to be controversial and start with those.

dbish
0 replies
1d9h

Those are usually called STOs for people who make the final call, not DRIs, from what I saw in my tenure there. The Amazon doc is a great concept when there are single threaded owners, however Amazon also has had culture and growth issues where “alignment” (like Google) became more important as team and orgs grew with multiple doc “owners” in direct contradiction of what Bezos used to preach so it just becomes design by committee for new features and products. Org dependent of course but I think that was the Day 2 culture seeping in as Bezos moved on and the company grew.

s17n
6 replies
1d12h

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.

r0ze-at-hn
1 replies
1d10h

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.

larsrc
0 replies
1d1h

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.

underdeserver
0 replies
1d12h

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.

trelane
0 replies
1d4h

That, and to comply with bureaucratic requirements. And commenting on others' docs, to "show leadership."

I long for design docs that are worth more than their cost.

kaon_
0 replies
1d11h

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 :)

dietr1ch
0 replies
1d11h

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.

leoh
6 replies
1d13h

Does anyone know where to find a copy of go/greendoc?

danpalmer
2 replies
1d12h

There's almost nothing in the greendoc template, I'm not sure it's at all valuable outside of Google.

leoh
1 replies
1d12h

I worked at Google and respectfully disagree

danpalmer
0 replies
18h38m

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.

lrem
1 replies
1d13h

Why would you? If you feel the process is worthwhile replicating elsewhere, just use your own words for the couple paragraphs of instructions.

leoh
0 replies
1d12h

I don’t even really remember what the sections were any longer

runeblaze
0 replies
1d11h

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.

datahack
6 replies
1d4h

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
2 replies
1d4h

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
1 replies
1d3h

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
0 replies
17h2m

Google search has been steadily deteriorating for over 5 years now and shows no sign of getting better, ads might be slightly better placed.

cmrdporcupine
2 replies
1d4h

"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.

trelane
1 replies
1d1h

This is why they pay so high.

Ah, ah, ah. This is why they pay so high so far.

cmrdporcupine
0 replies
1d1h

Yes, I left just before (1 year) the bloodletting began. There was already a whiff that GSU refreshes weren't going to be as generous and perf was going to be tougher.

I predicted the layoffs a year before started.

iainmerrick
5 replies
1d8h

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
4 replies
1d3h

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
3 replies
1d1h

If

rockemsockem
2 replies
22h47m

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.

trelane
1 replies
21h14m

I meant more the overall system than the system changes in design doc itself. The new bits of the system one at least has a little control over.

rockemsockem
0 replies
20h41m

Ah, yes, there's less control there, lol.

n3storm
4 replies
1d9h

Was a "design doc" what get IMAP killed at Gmail then?

staticfish
3 replies
1d9h

I'm not fully understanding your comment. What do you think is happening or has happened to IMAP at Gmail?

staticfish
1 replies
22h55m

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
0 replies
22h8m

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

glimshe
3 replies
1d7h

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.

another2another
0 replies
4h1m

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
0 replies
12h56m

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.

ajkjk
3 replies
1d11h

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
1 replies
1d10h

Which aspect of the Amazon design doc culture that you loved the most?

ajkjk
0 replies
13h39m

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
0 replies
1d10h

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.

testfrequency
2 replies
1d5h

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
1 replies
1d4h

I don't see how design docs are the problem in your scenario

testfrequency
0 replies
1d4h

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.

jongjong
2 replies
1d12h

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
1 replies
1d12h

Perhaps read the section dedicated to this point: 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
0 replies
1d11h

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).

larsrc
1 replies
1d1h

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
0 replies
1d

Same here. I found the biggest beneficiary of a design doc was my own thinking process (Xoogler here)

dudus
1 replies
1d12h

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
0 replies
1d12h

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."

youngtaff
0 replies
10h58m

Would love to have seen the design doc for AMP…

yatz
0 replies
1d4h

Spot on, especially in large teams with a diverse set of skills.

ndjshe3838
0 replies
1d11h

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

methods21
0 replies
1d3h

How about some actual examples?

larsrc
0 replies
1d1h

Design docs are the _mise en place_ of software development.

ein0p
0 replies
1d1h

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.

djmips
0 replies
21h19m

"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?

alienchow
0 replies
1d3h

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.

_obviously
0 replies
1d12h

Remember, Google retains the right to copy databases as they're not copy protected.

ZainRiz
0 replies
1d

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

3vidence
0 replies
1d4h

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