Skip to content

Design Docs#

What are design docs?#

Design docs are a way to define software through natural language. Many software companies use them one form or another. They can be called different things, and be structured in different ways, but they all have the same goal: to communicate the design of a piece of software with others and facilitate feedback. You may hear them called Request for Comments (RFCs) as well. This is a term that comes from the Internet Engineering Task Force,1 but at this point its use has generalized.

How are Product Requirement Documents (PRDs) related?

While not specifically a design doc, a PRD is a symbiotic document that can be written in conjunction with design docs.

How are Architecture Decision Records (ADRs) related?

ADRs do a similar job to design docs, but are more focused on the decisions made. They often are written after the fact, and will contain a lot of the information that would be in a design doc.

Why write design docs?#

There are a few reasons to write design docs23:

  1. Increase transparency and communication amongst teams and stakeholders
  2. Catch potential architectural stumbling blocks before they get to production and are expensive to fix
  3. Provide an overview of how the system was built
  4. Provide a historical record of why decisions were made
  5. Scale knowledge sharing across the organization

This is not an exhaustive list, but it gives you a good idea of why writing design docs is important. The bottom line is that it will provide clarity both for you and for others, and be a helpful check on your ideas. I like Gergely Orosz's analogy4 when thinking about this:


Image
The Pragmatic Engineer

Structure of a design doc#

There is no one-size-fits-all structure for a design doc, rather it should be tailored to the needs of the project. But there are also some common elements that are usually included:

  1. Metadata like title, author, date, etc.
  2. Approvers, if needed
  3. Background / context
  4. Problem statement / motivation

After this, the structure can vary greatly. It really depends on what would be most useful for the project type or organization. I would recommend looking at some examples here to see what might work best for you. I personally like to include the following sections:

  1. Goals and non-goals5
  2. Design
  3. Drawbacks
  4. Alternatives considered (optional)
  5. Open questions (optional)

This is general enough that it works for most of my projects, and I can usually break out the Design section for more complex issues. If you are in a more structured organization, or your team's products are more specific, you may end up with a more structured template.

When should you write design docs?#

Should I write one at all?#

There is no hard and fast rule for when you should write a design doc, but usually its for non-trivial changes before meaningful work has started. If the change is small, then a full design doc probably isn't necessary. Joel Spolsky has a good rule of thumb: more than a week of work, or more than one person working on it.6

But following the general structure in short form can be a helpful mind exercise. The act of writing down your thoughts can help you clarify your ideas, and help you see potential issues. If you just start writing, you may work only on the parts that are most clear to you, and then realize that you missed something important.6 While other experts may disagree due to how time consuming the writing process can be,7 it is more time consuming to make a mistake in the implementation phase. You do not need to write a full design doc, but just follow the rough framework.

At what point in the project should I write one?#

Now let's assume you going to write a design doc. There are a few different ways to go about it. Orosz says that he has seen design docs written for in many different scenarios2:

  1. Prototype, then design doc + feedback, then build → This is useful for projects with a lot of unknowns, where prototyping can help to clarify the design
  2. Design doc + feedback, then build → This is useful for projects where there needs to be a lot of alignment, and getting feedback early is important
  3. Design doc, then build while getting feedback → This is useful for projects where the design doc is more for communication, and to prepare others for downstream work
  4. Build, then design doc → This is useful when the project got more complex than expected, and can be a useful historical artifact

Critiques#

  1. Writing a design doc can be time consuming, and may not be worth it for smaller projects. 7
  2. Design doc culture can get out of hand, when they get tied to promotions. You can end up writing for the wrong audience (promo committee), and not for the people who actually need it.8
  3. Without a strong framework, design docs can become unruly. They can end up being used as promotion evidence, overly technical, extremely wordy without much substance, or hand-wavy and lacking detail.9

Good resources#

Articles#

  1. [PAYWALL] The Pragmatic Engineer: Engineering Planning with RFCs, Design Documents and ADRs
  2. Design Docs at Google
  3. Joel on Software: Painless Functional Specifications
    1. Part 1: Why Bother?
    2. Part 2: What’s a Spec?
    3. Part 3: But… How?
    4. Part 4: Tips
  4. Phil Calçado: A Structured RFC Process
  5. Hashicorp: Writing Practices and Culture
  6. Sourcegraph: Requests for comments (RFCs)

Examples#

  1. Chromium Design Docs
  2. Kubernetes Enhancement Proposals (KEPs)

  1. Request for Comments ↩

  2. Engineering Planning with RFCs, Design Documents and ADRs ↩↩

  3. Design Docs at Google ↩

  4. Companies Using RFCs or Design Docs and Examples of These ↩

  5. Goals and non-goals ↩

  6. Painless Functional Specifications - Why Bother? ↩↩

  7. When not to write a design doc. ↩↩

  8. YCombinator: s17n ↩

  9. YCombinator: acatton ↩