2 ms·

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 t

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

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