6 ms·

We write design docs at Google to communicate ideas with each other. They're useful for promo committees because effective communication between engineers is so

by skj 10y ago

We write design docs at Google to communicate ideas with each other. They're useful for promo committees because effective communication between engineers is something that is prerequisite for effective engineering. Of course a full design doc is not needed for every change. Many changes are small and straightforward. Only big things, where the team needs to discuss and understand options. Or bigger things, where directors etc need to sign off (not really design docs anymore, but same basic thing). The fact is that, on average, design doc+code takes less time than code without design (that is, without communication). Again, only for certain kinds of changes. Things go faster because problems are found, approaches are adjusted, or unmotivated features are axed.

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.
- 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.
Sacho 10y ago
How do you write design docs? Did you have to go through a course establishing some fundamentals to it? Did you take a writing class? Do you use specific tools? I would like to try and adopt this style of communication but everyone in my team, including me, are writing illiterates and I wouldn't even know where to start.
- fdsfsaa 10y ago
  I find the "five questions" approach helpful. The classic questions are "Who?", "What?", "Where?", "When?", and "Why?". If you answer those questions (probably best to start with "What?") and additionally address foreseeable questions and objections (e.g., "Why do you want to use Foo instead of Bar?" "Bar doesn't work on Spam data."), you have a good design document.
- euyyn 10y ago
  We don't really have a class: Like any writing, you just need to be aware of what's your goal. For a design doc, you want to say three things: (1) what are yo doing/planning to do, (2) why, and (3) what alternatives you've considered and why do you think they're worse. We just use Google Docs, and it's easy to share the doc and have people add comments or propose changes. There's a template somewhere, but I don't like it much.

by skj 10y ago

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

Sacho 10y ago

How do you write design docs? Did you have to go through a course establishing some fundamentals to it? Did you take a writing class? Do you use specific tools? I would like to try and adopt this style of communication but everyone in my team, including me, are writing illiterates and I wouldn't even know where to start.

fdsfsaa 10y ago
I find the "five questions" approach helpful. The classic questions are "Who?", "What?", "Where?", "When?", and "Why?". If you answer those questions (probably best to start with "What?") and additionally address foreseeable questions and objections (e.g., "Why do you want to use Foo instead of Bar?" "Bar doesn't work on Spam data."), you have a good design document.
euyyn 10y ago
We don't really have a class: Like any writing, you just need to be aware of what's your goal. For a design doc, you want to say three things: (1) what are yo doing/planning to do, (2) why, and (3) what alternatives you've considered and why do you think they're worse. We just use Google Docs, and it's easy to share the doc and have people add comments or propose changes. There's a template somewhere, but I don't like it much.