There are few habits on a high-quality, fast-shipping software team that are more important than one: writing good technical design docs.

Give me a few minutes and I’ll tell you about the many benefits, and how to get started.

Why write design docs?

While there are many benefits to writing a design doc, my personal north star goes something like this:

Make sure we’re building the right thing, and before it gets expensive to do something else.

Of course there are a litany of more discrete benefits, too:

  • Help you think, refine, and gain confidence in your plan. The first and sometimes only benefit is to you, the system’s author. The writing process forces you to build a plan and commit to it.
  • Explicitly confirm goals and non-goals. We all know that “over-engineering” should be avoided, but how would you actually say whether a design is doing that? Technical design docs set explicit, high-level goals for the work (what the design must achieve) as well as non-goals (things that are explicitly not necessary), against which the design is weighed.
  • Predict, assess, and solve for complexity. Software engineering problems often involve taming complexity. A design doc is an excellent place to predict complexity and then strategize on how to tame it.
  • Educate others
  • Help your future self
  • Help your future team

Essential parts of a design doc culture

In a high-functioning design doc culture, these are the major pieces.

The audience

The first thing to think about, and something you will keep in mind as a writer, is: who is a design doc for? You’re taking the time to write for someone, after all.

Your audience will vary from design to design, but it’s usually a mix of:

  • You! If nobody else reads this, you’re still important. A design doc helps you clarify and refine your design during the build, and will later serve as a historical record.
  • Teammates and internal experts. You’re rarely the only one affected by some work. Teammates who will have to review, support, and extend your design have an interest in understanding the work and seeing it done well. Plus, these are the people most likely to give you impactful feedback that improves the design.
  • Internal customers (aka stakeholders). Work often impacts other teams, if not external customers directly.
  • People in the mysterious future.

The doc itself

The review process

A design doc template

Here’s an exploded view of my typical design doc template.

  • Summary
  • Background
  • Proposal
    • Goals
    • Non-Goals
  • Detailed design
  • Work estimates
  • Alternatives considered
  • Summary - One sentence summary of the whole doc.

    “Technical design for an automatic invoicing system.”

  • Background - What must a reader know before diving in? Summarize by using links liberally.

    “Since day 1 we’ve manually processed our invoices. We’ve thought about automating it before <here>, but we didn’t have enough customers. Now we do, and our manual process is starting to fall over. The rest of this doc assumes you’re aware of the basics of invoicing.”

  • Proposal - Summary of the overall approach.

    “Build a new system called The Invoicer. It will read from the billing database and generate customer invoices every month.”

    • Goals - What absolutely must be achieved?

      “Automate invoice creation and customer emailing. Keep detailed logs at every step.”

    • Non-goals - What is deliberately not in scope?

      “Automate billing. Any payment collection is out-of-scope for this design.”

  • Detailed design - The technical plan. This should be done in enough detail to highlight consequential design decisions, and to spot potential challenges. The “meat” of any design doc, there’s no hard template for what goes within. Some topics and subsections that come up frequently:
    • Overall system diagram
    • New API endpoints (contract, description, and side-effects)
    • Component-by-component design choices (e.g. “Frontend”, “Backend”)
    • Changes in other systems/services
    • Migration/phased rollout design
  • Work estimates - This section serves a dual purpose: It highlights the size of the project overall, and should call out major phases. If the work involves a migration, a phased rollout, or other non-trivial deployment activities, those should be identified.
    • Building the system & launching in staging: 2 engineer-weeks.
    • Testing against sandbox data: 1 week.
    • Limited rollout (10 customers): 2 weeks to execute and fix any bugs.
    • Full rollout: 1 week to execute.
  • Alternatives considered - What could we do instead? A great section for anticipating your audience’s questions. This can be done at a high level (“why not buy instead of build?”) or deeper in the design (“why Postgres instead of Mongo?")—anywhere you considered a major alternative.
    1. Do nothing: The manual system would continue to work, but Bob in Finance says it’s taking upwards of 30 hours a week and becoming more error-proned. We have had 6 customer-impacting escalations due to errors here this quarter.
    2. Buy/outsource. We considered adopting Vendor X but found their solution and timeline inadequate. See more detailed analysis <here>.
  • Open questions - What is currently unknown, and what are the consequences of that? Ideally this section is closed out and empty before work begins; but since reality is messy, if you do have unknowns, it’s better to call those out. Your audience may even help you resolve them.
    • “Do we need to support xls export? Two customers use it but unclear if we should generalize & put in scope for this project. Open <ticket> with customer success to resolve.”
  • Privacy, security, and legal considerations -

Tips for writers

Pick the right level of detail

While some design docs end up quite large, many can be concise one-pagers. It all depends on the context of the problem and the size of that solution. In that spirit, you’re encouraged to vary how much you write.

For example, a design doc for a broadly-acknowledged, badly-needed system rewrite probably doesn’t spend as much time “making the case” (e.g. in Background) or do as much work evaluating alternatives, compared to a more speculative idea.

Know your audience

The best design docs predict and address the most likely questions your audience may have.

Whether or not you do an in-person design review, imagine yourself sitting in a room with all those people: What would the biggest expert or most vocal skeptic want to see motivated?

Knowing your audience also means you don’t need to re-hash topics the audience is presumed and required to know.

Tips for reviewers

Distinguish easily-changeable decisions from permanent ones

Tips for introducing design docs

1. Show, not tell

2. Be a good example

3. Be fast to offer help or feedback

No different than introducing a new programming language: If you’re the team’s de facto expert, you should be the most eager mentor to assist others getting off the ground.