At my place of work we probably wouldn’t follow this simply because we don’t love the design of Google’s products
Design Docs at Google
11–20 of 191 posts
Re: Design Docs at Google
#12Great article. I spend a lot of my time writing design docs these days. We derive a ton of value from it.
The projects I work on are typically collaborations with several developers. It is important to all have the same vision for what we are building. A good design doc is a vehicle for a team to sync their mental models of the thing they are building.
We also often have many other teams (security, infrastructure, operations, other business units, etc) who all have a stake in what we are doing. A good design doc helps build consensus with them. The review process gives them a voice in calling out concerns. It is much easier to solve a foundational problem before any code is written.
One addition that isn't explicitly called out by the article, but I have found very valuable, is the inclusion of references. In my experience, good design docs typically include some references. Links to the docs for a piece of software we want to use, links to an AWS blog post explaining part of the architecture we want to use, links to academic papers explaining the algorithms we want to implement, etc. Good references support the design doc and help readers fill in knowledge gaps they may have.
Re: Design Docs at Google
#13Design 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…
> Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it
I think this is a major benefit of design docs - they are a way to extend your engineering influence beyond your own individual output. If you write a design, and your design allows you and three other engineers to coordinate your efforts, then your engineering output is now "I coordinated a team to build something that any of us couldn't have written individually."
This dovetails nicely with your next point - uncovering blockers as early as possible is critical when coordinating a bunch of entities. Project plans are usually written on the assumption that every task will succeed, but there may be extra tasks added. If a task cannot be completed / you need to redesign something / etc, this will suddenly bring the work of N engineers to a halt. The earlier you successfully split the work into a series of known unknowns and implementation tasks, the better the project will go in general.
Re: Design Docs at Google
#14Author here. Let me know if you have questions or feedback.
My question is how do you avoid bikeshedding during this process?
Re: Design Docs at Google
#15Author here. Let me know if you have questions or feedback.
My question is how do you avoid bikeshedding during this process?
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.
Re: Design Docs at Google
#16I'm of a mind to reduce documentation as much as possible, or keep it as vague as possible.
That's because I came from an environment that insisted on incredibly detailed, formal, approved-by-everyone-including-the-mens-room-attendant, documents.
These became "concrete galoshes"[0] that turned what should have been an agile, iterative project into a waterfall behemoth that cost a mint, took forever to make, and delivered a result that no one wanted.
I suspect that my current process[1] would not be acceptable for many organizations, as it basically requires that everyone involved be extremely experienced, and kept together as a team for years.
I've actually come to realize that "tribal knowledge" is not the boogeyman that its made out to be; but is a way to get very high-quality, rapid, adaptive, development done. The main issue is that it does require good, empathetic management, long-term retention of experienced, capable people, and an "apprenticeship" model. These are not popular concepts in today's corporate world (at least, in the US).
[0] https://medium.com/chrismarshallny/concrete-galoshes-a5798a5...
[1] https://medium.com/chrismarshallny/forensic-design-documenta...
Re: Design Docs at Google
#17I like the idea of design documentation, but in 30 years of software development experience, I've never seen one done well. TFA does a reasonably good job of outlining what you'd want from an ideal design document but doesn't offer any advice on creating one that actually meets these criteria.
Re: Design Docs at Google
#18Any good examplars of docs that use this format?
Re: Design Docs at Google
#19Great article, generating consistent design docs that are both useful and not too time-consuming to create is something I am constantly working on. One thing I struggle with is finding examples of what others are doing in the industry. Does anyone have any resources they've found that provide examples of real-world design documents? Obviously each project is different but I'd be curious if others out there are publishing their templates/outlines of what they typically start with similar to this article.
I feel like blog posts seem to serve this niche for a lot of open source projects but it would be interesting to see if anyone has found more structured examples.
Re: Design Docs at Google
#20Does anyone know where to find real examples of design docs, possibly following this guide? I don't mean toy examples but something that's actually used by real people/orgs. My workplace has design docs but they're full of made-up words, so I'm pretty burned out by this kind of thing.