Design Docs at Google

Source: https://www.industrialempathy.com/posts/design-docs-at-google/

One of the key elements of Google's software engineering culture is the use of design docs for defining software designs. These are relatively informal documents that the primary author or authors of a software system or application create before they embark on the coding project. The design doc documents the high level implementation strategy and key design decisions with emphasis on the trade-offs that were considered during those decisions.

As software engineers our job is not to produce code per se, but rather to solve problems. Unstructured text, like in the form of a design doc, may be the better tool for solving problems early in a project lifecycle, as it may be more concise and easier to comprehend, and communicates the problems and solutions at a higher level than code.

Besides the original documentation of a software design, design docs fulfill the following functions in the software development lifecycle:

• Early identification of design issues when making changes is still cheap.
• Achieving consensus around a design in the organization.
• Ensuring consideration of cross-cutting concerns.
• Scaling knowledge of senior engineers into the organization.
• Form the basis of an organizational memory around design decisions.
• Acts as a summary artifact in the technical portfolio of the software designer(s).

Anatomy of a design doc

Design docs are informal documents and thus don't follow a strict guideline for their content. Rule #1 is: Write them in whatever form makes the most sense for the particular project. A certain structure has established itself as really useful:

Context and scope

Gives the reader a rough overview of the landscape and what is being built. Not a requirements doc. Keep it succinct. Entirely focused on objective background facts.

Goals and non-goals

A short list of bullet points of what the goals are, and more importantly, what non-goals are. Non-goals aren't negated goals but things that could reasonably be goals but are explicitly chosen not to be.

The actual design

Start with an overview and go into details. The design doc is the place to write down the trade-offs. Focus on those trade-offs to produce a useful document with long-term value.

Alternatives considered

Lists alternative designs that would have reasonably achieved similar outcomes. The focus should be on the trade-offs. One of the most important sections as it shows why the selected solution is the best.

Cross-cutting concerns

Security, privacy, observability. Google projects are required to have a dedicated privacy design doc.

The length of a design doc

Sweet spot for larger projects: around 10-20ish pages. 1-3 page "mini design docs" are also possible for incremental improvements.

When not to write a design doc

If the solution to the design problem is not ambiguous, there is little value. If a doc basically says "This is how we are going to implement it" without going into trade-offs and alternatives, it would have been better to write the actual program. The overhead of creating and reviewing a design doc may not be compatible with prototyping and rapid iteration.

The design doc lifecycle

1. Creation and rapid iteration - mostly in Google Docs with heavy collaboration features
2. Review - shared with wider audience. Can be lightweight (send to team-list) or heavy (formal design review meetings with senior audience)
3. Implementation and iteration - update the doc as plans collide with reality
4. Maintenance and learning - design docs are the first thing engineers look at when confronted with a new system. Authors should re-read their own docs a year or 2 later.

Conclusions

Design docs save money (avoid coding rabbit holes) and cost money (creation and review take time). When considering writing a design doc: Are you unsure about the right design? Would upfront time to gain certainty make sense? Is the problem or solution ambiguous?