One of the key elements of Google's software engineering culture is the use of design docs for defining software designs. These are...

Kirill Kurko

OpenAI

Community Picks is a section on daily.dev where our community members share the most interesting and valuable content they've discovered online. From insightful articles to handy tools, every post is a gem curated by our dedicated coomunity. To contribute to Community Picks, you need to have at least 250 reputation points, ensuring that only active and trusted members can share their finds.

Community Picks

Design docs at Google are informal documents that are used to define software designs. They serve the purpose of early identification of design issues, achieving consensus, ensuring consideration of cross-cutting concerns, scaling knowledge, forming an organizational memory, and acting as a summary artifact. Design docs should include a context and scope section, list out the goals and non-goals, provide the actual design with details, discuss alternatives considered, address cross-cutting concerns, and be of a sufficient detail but also short enough to be read by busy people. They should be written when the solution to the design problem is ambiguous and there is a need for organizational consensus, involvement of senior engineers, consideration of cross-cutting concerns, and documentation of legacy systems.

Design Docs at Google

I find design docs really useful, even if no one else reads them, because they force me to clarify my thinking before I start the (more expensive) process of implementation.
However, I’ve also noticed a couple of very common problems with design docs:
<ul>
<li>
Many design docs don’t clearly state the problem that the design is intended to solve. Often the best response to a design is “that problem isn’t important to solve”, or “there’s another system that already solves this problem”, or “there’s a totally different approach that you should consider”, but without a clear statement of the problem and why it’s important to solve, it’s hard to determine those kinds of things.
</li>
<li>
People often focus too much on the details of a design, vs. the important decisions that need(ed) to be made, the alternatives and rationale for those decisions, and the assumptions that they were based on. In a year, you probably won’t care that much about the details of the parameters of some API, but you probably will care a lot about why you chose that API over some other one, and it’s useful to have a record of that decision.
</li>
</ul>
It’s useful to view a design doc as a distillation of the thought process behind a system, vs. a high-level description of how to build something.