8 ms·

I don't think any specific type of change should require a design document. That framing presupposes too much hierarchy. Design documents, like code reviews and

by fdsfsaa 10y ago

I don't think any specific type of change should require a design document. That framing presupposes too much hierarchy. Design documents, like code reviews and tests, ought to be helpful tools for developers, not requirements imposed from above. I've worked at companies that didn't require design documents, but occasionally wrote them anyway because I wanted feedback. Another trigger could be a reviewer commenting, "Hey, this diff stack is getting pretty tangled. Can you write something that describes how it all fits together?" You should trust your developers' judgement.

acjohnson55 10y ago
While I agree with you in principle, I have my doubts that that approach works at "Google scale".
- fdsfsaa 10y ago
  What makes "Google scale" unique? I've never understood the argument that because Google serves ultraziggabytes of data, Google needs complex engineering practices. A program is the same program whether it runs on ten machines or ten thousand. Complexity is what matters, and while Google does solve very complex problems, other companies solve them too.
  - zardeh 10y ago
    I think the point is that every company that works at this scale does more or less the same thing out of necessity.
    - fdsfsaa 10y ago
      Saying that process is a necessary side effect of growth is like saying cancer is a necessary side effect of age. I don't think you have the causation quite right --- it's not necessity that forces the adoption of process exactly. Process is what you get by default if you don't consciously counteract natural human tendencies in management. A lot of large companies stop consciously protecting their culture, so they get the default big company culture instead. The default big company culture is ever-increasing process.
    - kuschku 10y ago
      Do they? Not even governments do that – instead, they manage billions of people and trillions of dollar by having a hierarchical structure, instead of using a long legislative process for every decision.
      - zardeh 10y ago
        Why do you think those two things are impossible to do at the same time. Most companies also have hierarchical structures, and most governments use some kind of bureaucratic process to approve major new projects, I'd expect it to be more bureaucratic than at most businesses.
        kuschku 10y ago
        But that’s even not the case, that’s the point. Most governments let their government agencies just do things, without unreasonable bureaucracies like these.
        zardeh 10y ago
        Really? Everything I'm familiar with has approval and review on everything in government, bureaucracy is synonymous with government to many people for exactly this reason.
zardeh 10y ago
(to be clear, this is all made up) Well let's put it this way, let's say that I'm a googler, I work on the android team and I want to rewrite the launcher from the ground up because I have some whiz-bang idea. This falls under my general purview of stuff that my team works on, so I grab my coworker, and for a month we hack away at it and have a good MVP. It has great improvements over the existing homescreen. We've been working and reviewing each other's code, and so after a month we submit the big change that touches bunches of files out for review by all of the various owners of various affected components. One of them shoots me an email a few minutes later and says that this work is all wasted because another team has been secretly working on an updated launcher for the release of Google's new flagship phone, the Pixel, it already has some of our features, but also has many others, and has been in development for 6 months already. So now my coworker and I have wasted 2 man-months of employee time on something. That's tens of thousands of dollars that goes poof when someone closes the pull request. And those 10s of thousands of dollars could have been saved with a 2 page document and a 1 hour meeting. The goal of these things is to not waste developer time, because you or I can't be aware of everything going on in a company, so writing a design doc allows other people to see what you're doing and 1. provide insight and feedback from their experience with similar problems 2. provide prior art from within the company 3. remind you of things you might have forgotten about 4. give you insight into how these changes will affect others 5. most importantly, give you information about other activities the company is doing in this direction that are related to your proposal, so that if you can avoid destructive interference, and potentially have constructive interference. Otherwise you end up with repeated work, wasted effort, and fragmentation.
- fdsfsaa 10y ago
  Coordination is important. I think you can achieve it without a formal design document and approval process. Your team could post a quick, informal message to a mailing list saying that you're going to work on a new launcher. The other launcher team could then reply and suggest getting together to talk about common plans and avoiding duplicate work. I'm not suggesting that communication is bad. I'm objecting strenuously (perhaps stridently) to the design document as a step in a rigid process and a requirement imposed from above. Personally, I'd rather see two teams work toward our improved hypothetical launcher than to see zero teams do that work because process imposed too high an "activation energy" on the launcher experiment. Also, why are both teams working in isolation for a month? If both teams check in code, the checkins themselves can provide an indication that other people are working in the same area. Incidentally, it's this effect that makes me strongly dislike feature branches. It's better to develop unstable code behind a feature flag, where the code is visible even if not active, than in a feature branch, where nobody can see it. (It's true that not all changes can be gated behind a flag, but most can be.)

by fdsfsaa 10y ago

acjohnson55 10y ago

While I agree with you in principle, I have my doubts that that approach works at "Google scale".

fdsfsaa 10y ago
What makes "Google scale" unique? I've never understood the argument that because Google serves ultraziggabytes of data, Google needs complex engineering practices. A program is the same program whether it runs on ten machines or ten thousand. Complexity is what matters, and while Google does solve very complex problems, other companies solve them too.
- zardeh 10y ago
  I think the point is that every company that works at this scale does more or less the same thing out of necessity.
  - fdsfsaa 10y ago
    Saying that process is a necessary side effect of growth is like saying cancer is a necessary side effect of age. I don't think you have the causation quite right --- it's not necessity that forces the adoption of process exactly. Process is what you get by default if you don't consciously counteract natural human tendencies in management. A lot of large companies stop consciously protecting their culture, so they get the default big company culture instead. The default big company culture is ever-increasing process.
  - kuschku 10y ago
    Do they? Not even governments do that – instead, they manage billions of people and trillions of dollar by having a hierarchical structure, instead of using a long legislative process for every decision.
    - zardeh 10y ago
      Why do you think those two things are impossible to do at the same time. Most companies also have hierarchical structures, and most governments use some kind of bureaucratic process to approve major new projects, I'd expect it to be more bureaucratic than at most businesses.
      - kuschku 10y ago
        But that’s even not the case, that’s the point. Most governments let their government agencies just do things, without unreasonable bureaucracies like these.
        zardeh 10y ago
        Really? Everything I'm familiar with has approval and review on everything in government, bureaucracy is synonymous with government to many people for exactly this reason.

zardeh 10y ago

(to be clear, this is all made up) Well let's put it this way, let's say that I'm a googler, I work on the android team and I want to rewrite the launcher from the ground up because I have some whiz-bang idea. This falls under my general purview of stuff that my team works on, so I grab my coworker, and for a month we hack away at it and have a good MVP. It has great improvements over the existing homescreen. We've been working and reviewing each other's code, and so after a month we submit the big change that touches bunches of files out for review by all of the various owners of various affected components. One of them shoots me an email a few minutes later and says that this work is all wasted because another team has been secretly working on an updated launcher for the release of Google's new flagship phone, the Pixel, it already has some of our features, but also has many others, and has been in development for 6 months already. So now my coworker and I have wasted 2 man-months of employee time on something. That's tens of thousands of dollars that goes poof when someone closes the pull request. And those 10s of thousands of dollars could have been saved with a 2 page document and a 1 hour meeting. The goal of these things is to not waste developer time, because you or I can't be aware of everything going on in a company, so writing a design doc allows other people to see what you're doing and 1. provide insight and feedback from their experience with similar problems 2. provide prior art from within the company 3. remind you of things you might have forgotten about 4. give you insight into how these changes will affect others 5. most importantly, give you information about other activities the company is doing in this direction that are related to your proposal, so that if you can avoid destructive interference, and potentially have constructive interference. Otherwise you end up with repeated work, wasted effort, and fragmentation.

fdsfsaa 10y ago
Coordination is important. I think you can achieve it without a formal design document and approval process. Your team could post a quick, informal message to a mailing list saying that you're going to work on a new launcher. The other launcher team could then reply and suggest getting together to talk about common plans and avoiding duplicate work. I'm not suggesting that communication is bad. I'm objecting strenuously (perhaps stridently) to the design document as a step in a rigid process and a requirement imposed from above. Personally, I'd rather see two teams work toward our improved hypothetical launcher than to see zero teams do that work because process imposed too high an "activation energy" on the launcher experiment. Also, why are both teams working in isolation for a month? If both teams check in code, the checkins themselves can provide an indication that other people are working in the same area. Incidentally, it's this effect that makes me strongly dislike feature branches. It's better to develop unstable code behind a feature flag, where the code is visible even if not active, than in a feature branch, where nobody can see it. (It's true that not all changes can be gated behind a flag, but most can be.)