6 ms·

> We write design docs at Google to communicate ideas with each other. I have no problem with individual developers choosing to circulate documents in order to

by fdsfsaa 10y ago

> We write design docs at Google to communicate ideas with each other. I have no problem with individual developers choosing to circulate documents in order to solicit feedback. My objection is to rigid processes that force engineers to write documents. Mandatory design documents for "communication" invariably morph into checklists of required signoffs from people who have little incentive to say "yes". In this way, a culture of design documents breeds a culture of extreme risk avoidance. It's a tragedy, really. Through numerous small steps, each apparently reasonable, a nimble organization becomes an ossified nightmare in which it takes six months to add a checkbox. > The fact is that, on average, design doc+code takes less time than code without design Prove it. Provide evidence. In my experience, your claim is not the case for most changes in most projects. For the changes where design documents facilitate development, my experience is that developers will choose to circulate documents even when not required to do so. > Unmotivated features are axed. One developer's "unmotivated feature" is another developer's essential use case.

zardeh 10y ago
To clarify here, what kinds of changes do you think require a design document?
- 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.
  - 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.)
jimmywanger 10y ago
> Prove it. Provide evidence. In my experience... That's amusing, that you want solid evidence, yet you're willing to use your own anecdotes. > Mandatory design documents for "communication" invariably morph into checklists of required signoffs from people who have little incentive to say "yes". Or they make you think about things that are not obvious on first glance, especially at Google scale. For any customer facing feature, you have to make sure that PII is taken care of, that security is implemented properly (SQL injection and XSS vulnerabilities for example), that internationalization is taken care of (especially right to left languages), and that UI fit and finish plays well with design guidelines, in both web and mobile, and that cross browser compatibility is at least thought about, as well as other issues. > One developer's "unmotivated feature" is another developer's essential use case. One developer's essential use case is another three dozen developers' backwards compatibility breaking change. > Through numerous small steps, each apparently reasonable, a nimble organization becomes an ossified nightmare in which it takes six months to add a checkbox. When you're serving up traffic at those volumes, with datacenters all over the world, accumulating revenue that quickly, yes, it's worth taking six months adding a checkbox to take every possible step possible to ensure that doesn't leak a security vulnerability somewhere. Just because your individual progress is slow, doesn't mean that the progress of the team is slow. One breaking change in say Google adwords can undo literally man years of work.
- fdsfsaa 10y ago
  > That's amusing, that you want solid evidence, yet you're willing to use your own anecdotes. I'm not the one presenting my anecdotes as fact: "The fact is that, on average, design doc+code takes less time than code without design". Anyway, you've very clearly articulated the conventional wisdom of big companies originating in a certain era of computing. Conventional wisdom isn't necessarily wrong, but it's not necessarily right for all time either. There are companies with data needs, user counts, and codebase sizes on par with Google that don't practice Google-style process, yet succeed anyway. That these companies have succeeded without Google's process is evidence that Google's process is unnecessary, at least in today's environment. > SQL injection and XSS vulnerabilities for example Code-level concerns. You're not going to stop SQL injection by looking at some high-level design document. The same goes for r2l text layout bugs. > it's worth taking six months adding a checkbox to take every possible step possible to ensure that doesn't leak a security vulnerability somewhere. Keep that in mind when smaller competitors surpass you. It's easy to say that Google's codebase represents 18 years of work. I strongly suspect that it wouldn't take so long to do starting today. Look at self-driving cars: how long has Google been working on them? How long has Uber? Whose cars are serving real-world passengers today? These days, we have 1) very good continuous integration systems, 2) good code review tools, 3) fast shipping vehicles, and 4) continually improving static analysis. These things were unavailable (at least at adequate quality levels) when Google started its design culture. Maybe the conventional wisdom you articulate might have been an optimum some time ago. These days, I think it's far too process-heavy and that Google and similar companies haven't kept up with the times. > Just because your individual progress is slow, doesn't mean that the progress of the team is slow It means that the team is inefficient. Communication overhead goes as N^2, after all. Google's teams are notoriously huge. When you see that a startup (or even another > $1 billion company) can do the same damn thing Google does and put a quarter of the people on the task, maybe it's time to wonder whether Google is doing something wrong. If developers feel like process is slowing them down, maybe you should listen to them. > One breaking change in say Google adwords can undo literally man years of work. It's easy to look at a few failures and conclude that you need to add process to fix whatever went wrong. It takes much more foresight and wisdom to see that this process probably costs more man years in overhead and inflexibility than you spend fixing the occasional mistake.
mdpopescu 10y ago
> Through numerous small steps, each apparently reasonable... I think I read somewhere that, on an online shop, each step you add to the checkout process halves the number of people who complete it. If true, that is a powerful argument for what you're saying. Also reminds me of Bastiat's "What is Not Seen". We don't see the developers who chose not to go through the whole process because it was too tedious.
- taneq 10y ago
  > I think I read somewhere that, on an online shop, each step you add to the checkout process halves the number of people who complete it. I wonder how much of that is just "more steps bad", and how much is that any step you add to a checkout process beyond what is necessary for the actual sale is (a) forcing you to do something you don't care about, and (b) going to make it more intrusive? Eg. forcing you to create an account, forcing you to validate an email address, forcing you to fill out a "quick survey", forcing you to unsubscribe from their marketing spam. There have been plenty of times that I've wanted to buy an item from an online store but have decided against it because the store wants to "create a relationship" with me instead of just selling me the damn item.

by fdsfsaa 10y ago

zardeh 10y ago

To clarify here, what kinds of changes do you think require a design document?

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

jimmywanger 10y ago

> Prove it. Provide evidence. In my experience... That's amusing, that you want solid evidence, yet you're willing to use your own anecdotes. > Mandatory design documents for "communication" invariably morph into checklists of required signoffs from people who have little incentive to say "yes". Or they make you think about things that are not obvious on first glance, especially at Google scale. For any customer facing feature, you have to make sure that PII is taken care of, that security is implemented properly (SQL injection and XSS vulnerabilities for example), that internationalization is taken care of (especially right to left languages), and that UI fit and finish plays well with design guidelines, in both web and mobile, and that cross browser compatibility is at least thought about, as well as other issues. > One developer's "unmotivated feature" is another developer's essential use case. One developer's essential use case is another three dozen developers' backwards compatibility breaking change. > Through numerous small steps, each apparently reasonable, a nimble organization becomes an ossified nightmare in which it takes six months to add a checkbox. When you're serving up traffic at those volumes, with datacenters all over the world, accumulating revenue that quickly, yes, it's worth taking six months adding a checkbox to take every possible step possible to ensure that doesn't leak a security vulnerability somewhere. Just because your individual progress is slow, doesn't mean that the progress of the team is slow. One breaking change in say Google adwords can undo literally man years of work.

fdsfsaa 10y ago
> That's amusing, that you want solid evidence, yet you're willing to use your own anecdotes. I'm not the one presenting my anecdotes as fact: "The fact is that, on average, design doc+code takes less time than code without design". Anyway, you've very clearly articulated the conventional wisdom of big companies originating in a certain era of computing. Conventional wisdom isn't necessarily wrong, but it's not necessarily right for all time either. There are companies with data needs, user counts, and codebase sizes on par with Google that don't practice Google-style process, yet succeed anyway. That these companies have succeeded without Google's process is evidence that Google's process is unnecessary, at least in today's environment. > SQL injection and XSS vulnerabilities for example Code-level concerns. You're not going to stop SQL injection by looking at some high-level design document. The same goes for r2l text layout bugs. > it's worth taking six months adding a checkbox to take every possible step possible to ensure that doesn't leak a security vulnerability somewhere. Keep that in mind when smaller competitors surpass you. It's easy to say that Google's codebase represents 18 years of work. I strongly suspect that it wouldn't take so long to do starting today. Look at self-driving cars: how long has Google been working on them? How long has Uber? Whose cars are serving real-world passengers today? These days, we have 1) very good continuous integration systems, 2) good code review tools, 3) fast shipping vehicles, and 4) continually improving static analysis. These things were unavailable (at least at adequate quality levels) when Google started its design culture. Maybe the conventional wisdom you articulate might have been an optimum some time ago. These days, I think it's far too process-heavy and that Google and similar companies haven't kept up with the times. > Just because your individual progress is slow, doesn't mean that the progress of the team is slow It means that the team is inefficient. Communication overhead goes as N^2, after all. Google's teams are notoriously huge. When you see that a startup (or even another > $1 billion company) can do the same damn thing Google does and put a quarter of the people on the task, maybe it's time to wonder whether Google is doing something wrong. If developers feel like process is slowing them down, maybe you should listen to them. > One breaking change in say Google adwords can undo literally man years of work. It's easy to look at a few failures and conclude that you need to add process to fix whatever went wrong. It takes much more foresight and wisdom to see that this process probably costs more man years in overhead and inflexibility than you spend fixing the occasional mistake.

mdpopescu 10y ago

> Through numerous small steps, each apparently reasonable... I think I read somewhere that, on an online shop, each step you add to the checkout process halves the number of people who complete it. If true, that is a powerful argument for what you're saying. Also reminds me of Bastiat's "What is Not Seen". We don't see the developers who chose not to go through the whole process because it was too tedious.

taneq 10y ago
> I think I read somewhere that, on an online shop, each step you add to the checkout process halves the number of people who complete it. I wonder how much of that is just "more steps bad", and how much is that any step you add to a checkout process beyond what is necessary for the actual sale is (a) forcing you to do something you don't care about, and (b) going to make it more intrusive? Eg. forcing you to create an account, forcing you to validate an email address, forcing you to fill out a "quick survey", forcing you to unsubscribe from their marketing spam. There have been plenty of times that I've wanted to buy an item from an online store but have decided against it because the store wants to "create a relationship" with me instead of just selling me the damn item.