Design Docs at Google
industrialempathy.com
Design Docs at Google
1–10 of 191 posts
Re: Design Docs at Google
#2Author here. Let me know if you have questions or feedback.
Re: Design Docs at Google
#3Author here. Let me know if you have questions or feedback.
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!
Re: Design Docs at Google
#4Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints.
I know this is fairly controversial, but our jobs isn't just to write code. Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it.
Design docs are a way to get all of that out of the way _before_ writing thousands of lines of code. The review process nets significantly different feedback to code reviews too.
Re: Design Docs at Google
#5Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints. I know this is fairly controversial, but our jobs isn't just to write code. Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it. Design docs are a way to get all of that out of the way _before_ writing thousands of lines of c…
> I know this is fairly controversial, but our jobs isn't just to write code.
I don't know if this is actually controversial, but I would not want to work at a place where this is controversial.
Re: Design Docs at Google
#6> Are you unsure about the right software design, and would it make sense to spend upfront time to gain certainty?
This is a great question to ask. It's human nature to lack foresight, especially when you are under pressure from deadlines, but in the long run it saves so much time.
Re: Design Docs at Google
#7Author here. Let me know if you have questions or feedback.
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).
Re: Design Docs at Google
#8Author here. Let me know if you have questions or feedback.
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 ?
Re: Design Docs at Google
#9Author here. Let me know if you have questions or feedback.
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 ?
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.
Re: Design Docs at Google
#10Author here. Let me know if you have questions or feedback.
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 ?
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).