5 ms·

Author here. Let me know if you have questions or feedback.

noselasd 6y ago
Actual real design docs would be extremely helpful
drewlander 6y ago
I thought it was very helpful. I am sending it out to my manager and others on our team. We have gone through a transition where I work, and a new product owner likes to send us implementation manuals as design docs because that's how they did things many years ago. We have been trying to get them to work in our process, and I am hoping that this article will help reinforce a change in thinking or at least help us to come to an understanding. Thank you for writing it!
010101010101 6y ago
This is great. At my company we normally create design docs, and I’ve seen each of the anti-patterns described here, along with their more informative/useful counterparts, but not seen a place that succinctly enumerates “do/don’t do” very well. 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).
fbunau 6y ago
How do you get teams that have knowledge on a particular piece put in the work when it is not one of their goals / focusing on other things ?
- cramforce 6y ago
  I know this isn't a satisfying answer, but tools like design docs or any $SoftwareDevelopmentMethodology do not help fix broken corporate governance. 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.
- numbsafari 6y ago
  What really helps here is adopting a culture of shared ownership. If a team has knowledge, your best bet is to work with them to share it with you. But if they are too busy, or otherwise unwilling, then you will be forced to move ahead without them. You can't let teams like that become a bottleneck to progress. 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).
- gowld 6y ago
  Pay people for producing value. If you believe design docs have value, pay people more for writing more better ones.
streblo 6y ago
My question is how do you avoid bikeshedding during this process?
- lhorie 6y ago
  The alternatives considered section is a good place to deal with it. There you can enumerate all the arguments for and against any particular thing, so you don't end up talking in circles. 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.
altgoogler 6y ago
Hi Malte! 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

Actual real design docs would be extremely helpful

I thought it was very helpful. I am sending it out to my manager and others on our team. We have gone through a transition where I work, and a new product owner likes to send us implementation manuals as design docs because that's how they did things many years ago. We have been trying to get them to work in our process, and I am hoping that this article will help reinforce a change in thinking or at least help us to come to an understanding. Thank you for writing it!

010101010101 6y ago

This is great. At my company we normally create design docs, and I’ve seen each of the anti-patterns described here, along with their more informative/useful counterparts, but not seen a place that succinctly enumerates “do/don’t do” very well. 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).

fbunau 6y ago

How do you get teams that have knowledge on a particular piece put in the work when it is not one of their goals / focusing on other things ?

cramforce 6y ago
I know this isn't a satisfying answer, but tools like design docs or any $SoftwareDevelopmentMethodology do not help fix broken corporate governance. 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.
numbsafari 6y ago
What really helps here is adopting a culture of shared ownership. If a team has knowledge, your best bet is to work with them to share it with you. But if they are too busy, or otherwise unwilling, then you will be forced to move ahead without them. You can't let teams like that become a bottleneck to progress. 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).
gowld 6y ago
Pay people for producing value. If you believe design docs have value, pay people more for writing more better ones.

streblo 6y ago

My question is how do you avoid bikeshedding during this process?

lhorie 6y ago
The alternatives considered section is a good place to deal with it. There you can enumerate all the arguments for and against any particular thing, so you don't end up talking in circles. 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.

altgoogler 6y ago

Hi Malte! 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