5 ms·

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

I do not share the same experience as the author, as someone working for the mentioned company. There is a wide range of types of design docs, and none of them are useful. I've rarely seen any useful design doc at Google. I feel that design docs are for engineers who are too much process-oriented. Here are the types of design docs I've encountered in the wild: * The promo design doc: it's not really explaining what this is trying to solve, it's more stating that this project is awesome, and makes the company better. The logical conclusion is that the author of this doc should be promoted. * The turbo-encabulator[1] design doc: this is a technobabble design doc which is full of terms never encountered before, and which is not understandable unless you're a senior member of the team. I'm sometimes not even sure the senior members of the team understand it... * The new-grad design doc: this a design doc with no substance, but as the person just graduated from university, they felt compelled to make is as long as possible, to prove... I don't know what... It is not conveying any information. They most likely copied/pasted huge chunks of the code they've already written, to fill most of the ~70 pages of the doc. * The made-up-facts design doc: this a design doc full of "everybody knows that", "they all say". Of course, it's not as obviously done as some politicians do it. But the design doc will push their design with "this follows good practices", "this software is slow, therefore..." who defined the good practice? why is it a good practice? what is slow? was it measured? is it an end user feeling? This is 99% of the design docs I've seen out there. Of course, exceptions exists, but they're very rare, in my experience. I'm shocked that the author pushes for this practice... But again, they were no engineer, they were a director, I guess design docs make sense for their position, for which I'm still trying to figure out the value these folks bring. [1] https://en.wikipedia.org/wiki/Turbo_encabulator https://en.wikipedia.org/wiki/Turbo_encabulator

mike_hearn 2y ago
That must have changed. I worked there from 2006-2014, back then most design docs were useful and followed the basic structure described in the article (minus the system context diagram). I noticed early on though, that design docs maintained in Google Docs tended to be of lower quality than those maintained in the version control repository. Not sure if that was just a proxy for when they were written or whether the code review process is just more rigorous than editing things in Docs, but the only time I wrote a large (40 page-ish?) design doc I did it using hand written HTML and we worked through the code review system, as was traditional. I also posted it to the central mailing list and web server and got feedback from employee number 3, which was nice. The central location made it easy to find them as they were sorted by category. Still I don't recall design docs being important enough to matter for a promotion by themselves. Promos were supposed to be about overall impact, not production of specific artifacts. Of course the system was badly flawed, and often yielded surprising decisions in a bad way, but I don't remember ever reading an obviously-optimized-for-perf design doc back then. If you can find the website that holds the design docs hand written in HTML from the earlier years, try perusing some of those and see if you find them more useful (or would have done when the systems were contemporary). Some of them old ones like SmartASS were full of detailed explanations of the underlying equations and models, which was quite helpful for understanding how it worked, as well as the explanations of why those approaches were chosen. Reading those helped informed my own design work later. I wasn't a director, just an engineer, and they did help. There are also some Chrome design docs linked to from the chromium.org website that I found helpful in the past for understanding its design.
- ryandrake 2y ago
  > 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 2y ago
    Traffic, revenue.
    - okdood64 2y ago
      That leaves out a lot of work that folks do that don’t affect either of those directly.
      - mike_hearn 2y ago
        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.
Cthulhu_ 2y ago
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?
- acatton 2y ago
  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?"
- mewpmewp2 2y ago
  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.
iainmerrick 2y ago
Yes! Although I think you forgot one, the "please just let me start coding" doc.
jppittma 2y ago
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.
apwell23 2y ago
> 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 2y ago
  If you are a googler, you should be using Bard.
  - apwell23 2y ago
    i am trying to get promoted not fired
danielvaughn 2y ago
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 2y ago
  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.
klabb3 2y ago
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.
rockemsockem 2y ago
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
alexchamberlain 2y ago
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?

mike_hearn 2y ago

That must have changed. I worked there from 2006-2014, back then most design docs were useful and followed the basic structure described in the article (minus the system context diagram). I noticed early on though, that design docs maintained in Google Docs tended to be of lower quality than those maintained in the version control repository. Not sure if that was just a proxy for when they were written or whether the code review process is just more rigorous than editing things in Docs, but the only time I wrote a large (40 page-ish?) design doc I did it using hand written HTML and we worked through the code review system, as was traditional. I also posted it to the central mailing list and web server and got feedback from employee number 3, which was nice. The central location made it easy to find them as they were sorted by category. Still I don't recall design docs being important enough to matter for a promotion by themselves. Promos were supposed to be about overall impact, not production of specific artifacts. Of course the system was badly flawed, and often yielded surprising decisions in a bad way, but I don't remember ever reading an obviously-optimized-for-perf design doc back then. If you can find the website that holds the design docs hand written in HTML from the earlier years, try perusing some of those and see if you find them more useful (or would have done when the systems were contemporary). Some of them old ones like SmartASS were full of detailed explanations of the underlying equations and models, which was quite helpful for understanding how it worked, as well as the explanations of why those approaches were chosen. Reading those helped informed my own design work later. I wasn't a director, just an engineer, and they did help. There are also some Chrome design docs linked to from the chromium.org website that I found helpful in the past for understanding its design.

ryandrake 2y ago
> 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 2y ago
  Traffic, revenue.
  - okdood64 2y ago
    That leaves out a lot of work that folks do that don’t affect either of those directly.
    - mike_hearn 2y ago
      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.

Cthulhu_ 2y ago

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?

acatton 2y ago
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?"
mewpmewp2 2y ago
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.

iainmerrick 2y ago

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

jppittma 2y ago

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.

apwell23 2y ago

> 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 2y ago
If you are a googler, you should be using Bard.
- apwell23 2y ago
  i am trying to get promoted not fired

danielvaughn 2y ago

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 2y ago
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.

klabb3 2y ago

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.

rockemsockem 2y ago

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

alexchamberlain 2y ago

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?