9 ms·

At Google, if you want to implement new features (or large refactoring), you'll need to write a design doc. In which, you should answer questions your reviewers

by yegle 10y ago

At Google, if you want to implement new features (or large refactoring), you'll need to write a design doc. In which, you should answer questions your reviewers might ask (common questions like: why do you want to do this, what are the alternatives, how components interactive with each other before/after your change). This is something like Python's PEP: you need a proposal to convince your reviewer that you have put thought into your change. Real world examples of these design docs can be found at https://github.com/golang/proposal https://github.com/golang/proposal

fdsfsaa 10y ago
Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what's possible. Google's design document culture is bad. Google has succeeded in spite of it. In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become increasingly out-of-date as the code evolves, creating anti-documentation that makes it take longer to understand code. Yes, yes, people should update design documents as the code evolves. Everyone knows that in practice, nobody updates old design documents. Design documents make it too easy for other developers to shoot down ideas. Sometimes the worth of code isn't apparent until it's made. It's far too easy for someone to comment "this will never work" on a proposed change. It's much harder for someone to deny benchmarks attached to a proposed change. It's too easy for reviewers to knock out functionality. Design documents turn every feature into a half-assed, lowest-common-denominator risk-minimized barely-adequate shell of itself. The real reason everyone at Google writes design documents is that promotion committees demand documents as "evidence of complexity". No design document, no impact. No impact, no promotion. Code is just code. Bad changes can be backed out. It's much better to move fast and iterate quickly than to create an illusion of care and add friction to every aspect of the development process. Up-front design of software just does not work. If it did, waterfall project planning would be successful. These questions you highlight --- Why are you making this change? What impact will it have? --- can be asked during review of actual code. There is no need to build a speedbump, not if you trust your people. Developers should be able to choose to create design documents and solicit feedback. Most changes don't need this process. You should trust developers to know what changes require a more extensive discussion and which ones don't. A culture that requires permissions and signoffs before work can begin is a culture that leaves products stagnant for years.
- stinkytaco 10y ago
  I can't comment on Google's culture, but: >Design documents turn every feature into a half-assed, lowest-common-denominator risk-minimized shell of itself. Sounds like a sentence written by someone who is an engineer and not a support staff or a user, i.e the people who have to deal with the fallout of every feature change and every engineering decision. I could just as easily substitute "feature driven design" into most of your points above. Requiring someone to put thought into the design of a product and to subject that thought to rigorous scrutiny is, on the whole, a good thing. One that leads to products end users want to use.
  - fdsfsaa 10y ago
    > Sounds like a sentence written by someone who is an engineer and not a support staff or a user Do support staff and users sign off on design documents? "No" is the universal answer. Are you claiming that engineers aren't reasonable human beings who can take support staff and user concerns into account on their own? What makes you think the people reviewing design documents can do that? Is it that you just trust a subset of engineers to understand the big picture? Are most engineers just drones? You shouldn't hire people who don't give enough of a shit to take the big picture into account. I am an engineer. I am also a user. I do support my software. I've been programming for twenty years. I find that "rigorous scrutiny" hurts more often than it helps. Maybe this rigid scrutiny was more appropriate in a world with release cycles measured in years, but we don't live in that world anymore. When you ship every week, you can easily undo mistakes, and you're better off erring toward iteration.
    - zardeh 10y ago
      >You shouldn't hire people who don't give enough of a shit to take the big picture into account. At a certain point you can't. I was recently asked to implement a feature for a usecase for another engineer. It required a design doc and review by a few representatives from related teams. He and I wrote the doc, and the initial review was that any solution that would fix his usecase would break the testing infrastructure for practically every other developer in the building. He could write a few fewer loc when testing, at the cost of tests failing due to unrelated changes. Neither he nor I had the awareness of the impact, and realistically couldn't have, it was neither of our responsibilities. And because I spent an hour filling out a template document, I didn't need to waste my time doing that.
nathancahill 10y ago
As a less formal version of PEP/design docs, I always open an issue on Github projects proposing the changes that I would submit in a PR before I do the work, and end by asking if there's interest in a PR that implements those changes. That requires very little effort and avoids a lot of wasted time on both sides.
- scaryclam 10y ago
  This, unless my PR is addressing an already open issue. For larger ideas/changes that may be difficult to explain, I may open an initial PR, but make it clear that it's for illustrative purposes and that I don't expect it to be accepted or to remain open. On occasion I've saved myself a whole lot of time when one of the maintainers agrees with the proposal and reveals they're working on something very similar already.
drubio 10y ago
Google isn't an engineering paragon anymore, it's too large. I speak from what I've seen in how they handle their development & releases for Angular 2, which is a fairly large project with an equally large community. Take a look at this release candidate, which is in between other release candidate RC.5. It has over 100+ breaking changes with new features https://github.com/angular/angular/blob/master/CHANGELOG.md#user-content-200-rc5-2016-08-09 https://github.com/angular/angular/blob/master/CHANGELOG.md#... This is practically against against all definitions of what a release candidate should be: https://en.wikipedia.org/wiki/Software_release_life_cycle#Release_candidate https://en.wikipedia.org/wiki/Software_release_life_cycle#Re... . So this neatly painted blanket statement of 'at google' we do x,y,z for development, new features & reviewers isn't true. There are very messy projects & development practices, practically like at any other large company.

by yegle 10y ago

fdsfsaa 10y ago

Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what's possible. Google's design document culture is bad. Google has succeeded in spite of it. In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become increasingly out-of-date as the code evolves, creating anti-documentation that makes it take longer to understand code. Yes, yes, people should update design documents as the code evolves. Everyone knows that in practice, nobody updates old design documents. Design documents make it too easy for other developers to shoot down ideas. Sometimes the worth of code isn't apparent until it's made. It's far too easy for someone to comment "this will never work" on a proposed change. It's much harder for someone to deny benchmarks attached to a proposed change. It's too easy for reviewers to knock out functionality. Design documents turn every feature into a half-assed, lowest-common-denominator risk-minimized barely-adequate shell of itself. The real reason everyone at Google writes design documents is that promotion committees demand documents as "evidence of complexity". No design document, no impact. No impact, no promotion. Code is just code. Bad changes can be backed out. It's much better to move fast and iterate quickly than to create an illusion of care and add friction to every aspect of the development process. Up-front design of software just does not work. If it did, waterfall project planning would be successful. These questions you highlight --- Why are you making this change? What impact will it have? --- can be asked during review of actual code. There is no need to build a speedbump, not if you trust your people. Developers should be able to choose to create design documents and solicit feedback. Most changes don't need this process. You should trust developers to know what changes require a more extensive discussion and which ones don't. A culture that requires permissions and signoffs before work can begin is a culture that leaves products stagnant for years.

stinkytaco 10y ago
I can't comment on Google's culture, but: >Design documents turn every feature into a half-assed, lowest-common-denominator risk-minimized shell of itself. Sounds like a sentence written by someone who is an engineer and not a support staff or a user, i.e the people who have to deal with the fallout of every feature change and every engineering decision. I could just as easily substitute "feature driven design" into most of your points above. Requiring someone to put thought into the design of a product and to subject that thought to rigorous scrutiny is, on the whole, a good thing. One that leads to products end users want to use.
- fdsfsaa 10y ago
  > Sounds like a sentence written by someone who is an engineer and not a support staff or a user Do support staff and users sign off on design documents? "No" is the universal answer. Are you claiming that engineers aren't reasonable human beings who can take support staff and user concerns into account on their own? What makes you think the people reviewing design documents can do that? Is it that you just trust a subset of engineers to understand the big picture? Are most engineers just drones? You shouldn't hire people who don't give enough of a shit to take the big picture into account. I am an engineer. I am also a user. I do support my software. I've been programming for twenty years. I find that "rigorous scrutiny" hurts more often than it helps. Maybe this rigid scrutiny was more appropriate in a world with release cycles measured in years, but we don't live in that world anymore. When you ship every week, you can easily undo mistakes, and you're better off erring toward iteration.
  - zardeh 10y ago
    >You shouldn't hire people who don't give enough of a shit to take the big picture into account. At a certain point you can't. I was recently asked to implement a feature for a usecase for another engineer. It required a design doc and review by a few representatives from related teams. He and I wrote the doc, and the initial review was that any solution that would fix his usecase would break the testing infrastructure for practically every other developer in the building. He could write a few fewer loc when testing, at the cost of tests failing due to unrelated changes. Neither he nor I had the awareness of the impact, and realistically couldn't have, it was neither of our responsibilities. And because I spent an hour filling out a template document, I didn't need to waste my time doing that.

nathancahill 10y ago

As a less formal version of PEP/design docs, I always open an issue on Github projects proposing the changes that I would submit in a PR before I do the work, and end by asking if there's interest in a PR that implements those changes. That requires very little effort and avoids a lot of wasted time on both sides.

scaryclam 10y ago
This, unless my PR is addressing an already open issue. For larger ideas/changes that may be difficult to explain, I may open an initial PR, but make it clear that it's for illustrative purposes and that I don't expect it to be accepted or to remain open. On occasion I've saved myself a whole lot of time when one of the maintainers agrees with the proposal and reveals they're working on something very similar already.

drubio 10y ago

Google isn't an engineering paragon anymore, it's too large. I speak from what I've seen in how they handle their development & releases for Angular 2, which is a fairly large project with an equally large community. Take a look at this release candidate, which is in between other release candidate RC.5. It has over 100+ breaking changes with new features https://github.com/angular/angular/blob/master/CHANGELOG.md#user-content-200-rc5-2016-08-09 https://github.com/angular/angular/blob/master/CHANGELOG.md#... This is practically against against all definitions of what a release candidate should be: https://en.wikipedia.org/wiki/Software_release_life_cycle#Release_candidate https://en.wikipedia.org/wiki/Software_release_life_cycle#Re... . So this neatly painted blanket statement of 'at google' we do x,y,z for development, new features & reviewers isn't true. There are very messy projects & development practices, practically like at any other large company.