Things I Learned at Google: Design Docs

This is part three of a multi-part series on lessons I learned while working as a software engineer at Google. If you’d like to start at the beginning, check out part zero.

Essentially, design docs describe a plan for solving a problem. Teams at Google generally require engineers to write design docs before any significant change (or set of changes) to a product or service. These docs serve a number of useful purposes:

• Planning: Design docs often begin from the author’s notes as they attempt to figure out what approach (if any) can address the problem they hope to solve. After a doc is complete it can serve as a reference for the breakdown of the work involved.
• Structure: Teams usually have doc templates with predefined sections which prompt authors to consider necessary aspects of their plan. These can vary from widely applicable (‘test plan’, ‘backwards compatibility’) to domain-specific (‘accessibility’ for frontend work, ‘quota impact’ for API changes).
• Discussion: In review, design docs provide a venue for teams to discuss multiple approaches, collaborate, and coordinate.
• Approval: It is conventional to have one or more colleagues listed as ‘reviewers’ on a design doc. While less formal than Google’s code review process, this is another form of multi-party approval gating product or service changes. For larger scope projects, approval of a doc may serve as a more formal ‘go-ahead’ from a senior manager or Director.
• Record: After a project is complete, a design doc becomes an archival tool. Years later it can serve as a reference for why a particular design choice was made (and why others weren’t).
• History: Design docs are a tangible artifact of the problem-solving process needed to build and maintain software. At a large company like Google their existence can help engineers receive credit for work that might otherwise seem nebulous to managers (though there are negative impacts of design docs’ influence on performance reviews as well).

Design docs are largely an efficiency tool. By requiring engineers to specify their approach in detail before beginning work, infeasible approaches are often caught before significant time is wasted on their implementation. Document review socializes plans within a team and creates a ‘plan of record’ capable of sustaining projects through personnel and organizational changes.

A reviewed document also provides useful context for code reviewers who may see only isolated, intermediate changes that are part of a larger objective. Building and maintaining software over time comes with significant coordination challenges; design docs fight these challenges by pulling coordination overhead from the future to the present, thereby reducing its cost.

Advice for authors: take responsibility

Design docs are a communication exercise. You, as the author, have a plan for implementing a change. For efficiency reasons (see above) it is desirable for your colleagues to understand the nature of the change you are proposing and the rationale for your approach.

You are responsible for ensuring this understanding takes place. Your design doc should be a vessel that delivers your ideas in their most consumable form. Make intentional choices in structure, detail, and wording to accomplish this goal.

Advice for authors: remember your audience(s)

Design docs serve many purposes and many audiences. Provide the necessary context and background information for your approach to be understood by readers.

Remember that you are (likely) the world’s foremost expert on the solution you are proposing; in comparison, your team members (and doc reviewers) may have contemplated it slightly or not at all. Does your doc ferry them through the thought process of understanding your proposed approach from a position of relative ignorance?

Remember that your doc may be read by future team members you will never meet. Will it help them understand the decisions you made?

Remember that your doc may be read by other managers as part of a performance review process. Will the nature of your work be clear to them?

My preferred doc structure

Over time I have settled on a structure for my design docs that I find effective:

• Title: A short, descriptive title (<6 words, often ending in ‘design’) and accompanying shortlink. Underneath the title I include metadata as body text: usernames of authors, usernames of reviewers, the document status (either ‘draft’ or ‘final’), and a ‘last updated’ date.
• Purpose: A 1-2 sentence statement of what the document contains, often beginning “This document describes a design for…”. By the end, readers should be confident they have opened the correct document. It is not necessary to provide context for terms.
• Background: A 1-2 paragraph explanation of the context for the changes described in the document, including the motivation for your proposal (a bug, a customer need, etc.). This should be written such that it is accessible to any employee at your company, explaining the relationship between relevant products or services and linking terms to relevant documentation. By the end, readers should understand the existing state of the world and have the context necessary to understand your proposal.
• Overview: A 1-2 paragraph summary of your design. This should highlight the high-level changes you are proposing and any details or consequences of particular concern to readers.
• Detailed design: This section is the meat of the document and contains a structured description of the changes you would like to make. I typically break this section into subheadings (and sub-subheadings), dividing the project by its individual features and the systems where the changes will take place. This section should be as long as necessary to communicate your proposed changes. When deciding what level of detail to include, a good standard is that any design or implementation decision that could provoke significant discussion in code review should be explained here. Depending on the scope of the project this may take many pages!
• Alternatives considered: The purpose of this section is to note other clear options (whether conceptual or in implementation) and directly address why they were not selected. While this section can preempt questions from reviewers, it is most useful to future readers.
• Secondary sections: Depending on the specific context there are likely secondary concerns that should be addressed in standalone sections. How will your changes be tested? How will your changes be deployed? How will your changes be monitored or evaluated? Particular concerns that are not well–suited to the flow of the ‘detailed design’ section can be addressed in these sections.
• Document history: A table indicating the major milestones of the document and their dates. At a minimum this should include ‘Initial draft’ and ‘marked final’ (when the status of the doc is changed to ‘final’ after approval from reviewers). If the contents change substantially during review it can be helpful to note that here as well.

This structure is not original; most design docs at Google contain many of these sections. However, no formula or document template can accomplish this communication exercise for you. The intent of the sections is what pursues this goal – without that, the organization is mostly worthless.

I arrived at this approach iteratively, by seeing what worked (and didn’t) in my own docs and by applying the same lens to others’ writing. A different approach may work for you; experiment and look around for what works and what doesn’t.

Different types of docs

Every project is different; adapt your writing to the communication exercise at hand. The most variable parts of the design docs I write are the structure of the ‘detailed design’ section and the list of secondary sections.

For small projects (down to even an individual thorny code change), I sometimes write a ‘one-pager’[0] that follows an abbreviated structure: Background, Overview, and Proposed Changes. A doc like this can be written in less than an hour and can provide the same discussion and archival benefits of larger docs.

Tone, grammar, and clarity

It is worth reiterating: design docs are a communication exercise. My experience is that document readers do not distinguish between content and form when judging documents. In other words, if your document reads like crap then readers will infer that your ideas are crap.

In the pursuit of effective written communication, I recommend applying a consistent tone (or ‘voice’) to your design docs. With practice you may find that a particular written style comes to you naturally. Another good option is emulating the style of docs you find effective. This is not creative fiction; consistency is a virtue.

Make a strong effort to avoid glaring grammatical errors like sentence fragments, missing punctuation, and misspellings. There are abundant automated tools that can help with this if you need them.

Some people are under the mistaken impression that their docs are more effective (or impressive) the longer they are. Superfluous information imperils the communication exercise in the same way as grammatical mistakes; make the most of your readers’ limited attention by being as concise as possible.

[0] It is a running joke at Google that documents labelled as ‘one-pagers’ are sometimes multiple times longer than that. While it is difficult to condense any design to a single page, I consider two pages the highest acceptable limit for this label.