Author here. Let me know if you have questions or feedback.
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
Often times, the person writing the document has the most context/expertise and can provide a short explanation for why one option might be a better trade-off than another even though there are clear and logical arguments against it.
Having data also helps. IMHO, a lot of bikeshedding is uneducated conjecture, which can be put to rest with proof-of-concepts, benchmarks, level headed comparison tables, discussion notes with others in the industry etc. At my company, large reaching technological decisions often involve meeting with people with relevant experience from FAANG/others to gather information.
A piece of feedback - I like to include sequence diagrams along side system diagrams to detail interactions a bit. I think this serves a similar purpose to documenting the API in an informal manner, and gives a good amount of information density (I _don’t_ expect everyone to read and digest all 5-15 pages of a document, pictures help people retain what’s important and also have a small thing to refer to in the future, IMO).
Concretely here, I'd try to make solving my problem the other team's goal. E.g. by inviting them to a summit during planning season and agree on common OKRs.
Similarly, if you are on a team that has important knowledge, it's really important to share that knowledge widely. Prepare lots of good resources to help spread that knowledge. Don't try to operate as gatekeepers or a cabal, instead, it's up to you to be an advocate and an activist for your knowledge. If you want other teams to respect your team's knowledge, then you need to make sure that they recognize that you have it, and that you are willing to share it. Lastly, it's best to adopt a strategy of empowerment, rather than ownership. Encourage and support consumers of your knowledge to help themselves, rather than requiring you to opine on every single question, or participate in every single design review.
All of this, of course, takes leadership, because it's a cultural practice. Leadership has to invest in having teams document and share knowledge. Leadership has to reward and recognize knowledge sharers while similarly recognizing and working with knowledge hoarders to change their ways. Leadership has to identify when a team has become a blocker on progress and either add resources, or as noted above, encourage teams to work around them. "So and so is the networking expert but he won't help us fix this problem." "Okay, I'll work on getting his time, meanwhile let me find this outside consultant or I'll give you cover to do the work yourself since they are blocking."
That last thing is your last resort, but you need to not be afraid to use it. I actually get the impression that Google suffers from that quite a bit (the existence of Principal Engineers who "squat" on problems is one I've seen discussed repeatedly by former employees, and something I've witnessed on OSS projects).