Great article. I've agree that design docs are great part of what defines engineering culture at Google. I'd recommend to anybody who will listen that their company should do it also.
Lots of people in this thread were burned by waterfall-esque requirements documents or formal specification, and I'd like to point out why I think design documents (at Google at least) are different and more effective than those things.
I like to think of design docs as not an artifact produced by a project but as a communication mechanism of a team. You have an idea and you write down:
* What are you trying to do?
* Why are you doing to do it?
* How are you going to do it?
* What considerations have you made?
Then you socialize it to one or two reviewers, who ask a lot of questions, then you take it to your team, who ask (relatively fewer) questions. The socialization part is key to the entire system. As you note:
"The primary value that such reviews add is that they form an opportunity for the combined experience of the organization to be incorporated into a design. Most consistently, ensuring that designs take cross-cutting concerns such as observability, security and privacy into account is something that can be ensured in a review stage. The primary value of the review isn’t that issues get discovered per-se, but rather that this happens relatively early in the development lifecycle when it is still relatively cheap to make changes."
If I printed out your article to show people, this is the part I would highlight in yellow.
Contrast this with formal doc systems that rarely capture the "why" and "why nots". Future maintainers have a document that captures the thinking at the time, rather than trying to document the full implementation plan of a system.
Hopefully this adds some context to those who've been burnt by more traditional approaches.
Great article. I've agree that design docs are great part of what defines engineering culture at Google. I'd recommend to anybody who will listen that their company should do it also.
Lots of people in this thread were burned by waterfall-esque requirements documents or formal specification, and I'd like to point out why I think design documents (at Google at least) are different and more effective than those things.
I like to think of design docs as not an artifact produced by a project but as a communication mechanism of a team. You have an idea and you write down:
* What are you trying to do?
* Why are you doing to do it?
* How are you going to do it?
* What considerations have you made?
Then you socialize it to one or two reviewers, who ask a lot of questions, then you take it to your team, who ask (relatively fewer) questions. The socialization part is key to the entire system. As you note:
"The primary value that such reviews add is that they form an opportunity for the combined experience of the organization to be incorporated into a design. Most consistently, ensuring that designs take cross-cutting concerns such as observability, security and privacy into account is something that can be ensured in a review stage. The primary value of the review isn’t that issues get discovered per-se, but rather that this happens relatively early in the development lifecycle when it is still relatively cheap to make changes."
If I printed out your article to show people, this is the part I would highlight in yellow.
Contrast this with formal doc systems that rarely capture the "why" and "why nots". Future maintainers have a document that captures the thinking at the time, rather than trying to document the full implementation plan of a system.
Hopefully this adds some context to those who've been burnt by more traditional approaches.
edit: typos