[EXAMPLE] Design Document Template

Also see my Design Process Guide. By Joel Thornton.
Depending on the scale of your design, you may not need every single section in this design document template. Feel free to pick and choose what makes the most sense for your particular design, and add sections as appropriate. In general, this template represents important things to think about.

1 Overview

Write your high level "executive summary" here. Explain what problem you're trying to solve, why you are trying to solve it, and who your target customers are. Leverage the SMART model in formulating this. You may also want to talk about how this design helps achieve the team's long term vision.

Users have expressed widespread interest in being able to author documents in the wiki using Markdown syntax, which is widely used and easy to use for non-technical as well as technical users. This design details the work required to support authoring and viewing wiki documents written in Markdown syntax.

1.1 Who is the customer?

Document in a sentence or two who your customer is.

1.2 Key objectives

Write your key objectives here. These are the high level "cardinal points" that outline the problem that needs to be solved. These objectives should drive further discussion as you drill down into the requirements, design, and implementation work.
  • Pages should be authorable using standard Markdown syntax.
  • Non-technical users should be able to author pages using a WYSIWYG editor which generates Markdown.
  • All pages authored with Markdown should be rendered correctly when viewed.

2 Requirements

2.1 Glossary

Outline any terms that your audience needs to know to know this document, but may not already understand. This includes terms created in the course of this design.
word 1
definition 1
word 2
definition 2

2.2 User stories

Provide a list of requirements using User Story language. Each requirement should include an indication of its priority. P0 = Must Have. P1 = Should Have. P2 = Nice to Have. (Lower priority items should be in 'Out of scope' section.)
 Priority   Requirement
P0 As a reader, I want to be able to read pages rendered from Markdown syntax, so that I can view pages which have been written in Markdown.
P0 As a technical author, I want to be able to author pages in Markdown using the source editor, so that I can quickly write documents in native Markdown syntax.
P1 As a non-technical author, I want to be able to author pages in Markdown using the WYSIWYG editor, so that I can quickly write documents without any knowledge of Markdown syntax.
P2 As an author, I want to be able to add custom CSS styling into my Markdown-based pages, so that I can customize and beautify the styling of my documents.

2.3 Out of scope

Call out any requirements that are explicitly not part of this design, but which a stakeholder might assume to be included in the design. Doing this helps clarify and constrain the design.
  • More advanced Markdown features such as the Markdown Extended Syntax

2.4 Success metrics

How do we determine when the implementation is finished and correct? Define the success criteria in terms of quantifiable metrics that relate back to the key objectives, and mention how we'll collect those metrics. Refer to the SMART criteria for guidance here.
  • At least 100 pages have been created using Markdown syntax one month after release. These metrics will be gathered from a SQL query against the Prod DB.
  • At least 1000 page views have occurred on Markdown pages one month after release. These metrics will be gathered from a SQL query against the Prod DB.

2.5 Security classification

What is the expected security classification of the data that the implementation will be working with?

2.6 Assumptions

Call out any assumptions being made in this design which play a significant role in how the requirements have been defined, or how the implementation will be carried out. It's important to identify these because they will often become a point of discussion during reviews and can help flesh out the implementation details. These may also be red flags that justify doing some prototype work up front before moving into the implementation design phase.
  • A readily available Markdown renderer is available to be incorporated in the wiki platform.

2.7 Risks

Identify any known or potential risks with the intended design.

2.8 Caveats

Call out any warnings, limitations, or other caveats pertinent to the design. It's important to be clear about the issues that the design cannot solve, or additional complications that it may introduce outside of the direct domain of the design's implementation.

3 Design summary

Present a high level description of the intended design. This can be a BIG section of the document! Feel free to get as detailed as needed here. Add or remove subsections as appropriate below.

3.1 Expected scale

What is the scale that the implementation is expected to support? Consider describing this in terms of transactions per second (TPS). Be sure to discuss projected growth rates here.

3.2 Expected lifetime

How long is the implementation expected to live for? Oftentimes this will be "indefinitely", but call out any assumptions about this here.

3.3 Expected costs

If there any significant new up-front or ongoing financial costs implied by the implementation, call those out here. For example, will it be necessary to stand up a new fleet or datastore, or scale up an existing one to handle an additional load imposed by the new implementation?

3.4 Design constraints

Are there any constraints on the shape that the design/implementation must take that aren't directly described by the requirements? For example, does the implementation need to be constrained to a certain part of the codebase? Does the data need to live in a certain part of the system? Are there existing workflows or subsystems that need to be integrated with? Are there legal restrictions? 

3.5 Division of responsibilities

When multiple teams will be collaborating on the implementation effort, we should clearly delineate who is responsible for which aspects of the work.
Add those details here, and/or if it makes sense, add a "Responsible party" column to the Requirements table.

3.6 Technology choices

What tool(s) did we decide to use? For each tool, is there a specific version we should be using? Why or why not? Did you consider future support/EOL products? What alternative choices did we consider, and why did we reject them?

3.7 Failure cases

How will different possible failure cases be accounted for? Think about: dependent service outages, fleet outages, deployment failures, data synchronization issues, system bottlenecks, authentication failures (e.g. no Kerberos token), authorization failures (e.g. permission denied messages). In each failure case, consider how the customer experience will be managed. Also consider how the team can recover from failure scenarios and what work may be needed to meet team SLAs.

3.8 Compatibility

Not every design will have compatibility-related issues to account for, but think about the potential for such issues and detail them here:

  • What is needed to ensure backwards compatibility and prevent compatibility breakages? For example, if are we changing the interface of some existing component, how do we ensure this won't break existing usages of the component?
  • How does the design ensure forwards compatibility? For example, if the design exposes a JSON REST API, does it make sense to have a version-number in the JSON payload?
  • Is any additional work needed to ensure continued compatibility with some external dependencies? For example, does the design depend on a service whose interface is expected to change in the near future?
  • Are we changing the user interface/experience in some way that may confuse our customers, or violate their current expectations? For example, if the design dramatically changes a common user workflow, how are we accounting for that from the customer's perspective?

3.9 Diagrams

Include diagrams covering client interactions, downstream service interactions, complicated internal calculations/architectures, and anything else that helps a reader understand how the pieces will fit together and how work/data will flow through the system.

3.10 Design rationales

Discuss the reasons behind why this particular design was chosen to satisfy the requirements. Why are we doing it this way? If there is another solution that might seem more obvious, why didn't we use that approach?

3.11 Metrics

For many designs, it won't make sense to itemize specific metrics until implementation time. Just call out key metrics from the perspective of the design/requirements here.

3.12 Alarms

For many designs, it won't make sense to itemize specific alarms until implementation time. Just call out key alarms from the perspective of the design/requirements here.

3.13 Release

Noteworthy specifics about the release process: deployment particulars, obtaining needed approvals, pre-mortem, gameday, user acceptance testing, alpha/beta/gamma testing, dashboarding work, runbook updates, etc.

Please call out what the requirements are for release. For example:

  1. How are we communicating the release to customers? (FAQ/Email/...)
  2. How much customer pushback/interaction do we expect to see?
    1. Do we have a stance to respond to our customers?
  3. Is there any work required on our end (either on-call or team)?
  4. Can/should this work be automated?
  5. Do we need a canned response?
  6. Are there any exception/edge cases that we need to respond differently to?

3.14 Maintenance

Will there be any expected ongoing maintenance effort required? Examples: periodic scheduled tasks, taking mandatory version updates on dependencies, additional oncall duties that will be needed, etc.

3.15 Rejected designs

3.16 Open questions

4 Implementation plan

Detail the high level implementation targets/milestones, with bug tracker issue links and estimates for how much work will be required for each. As this section is fleshed out you may want to break this up in a way that makes sense - for example, you may want to carve the plan up into a sequential series of phases, with each phase containing several parallelizable targets.

Master issue:  2741

 SIM   Target   Estimated work (dev-weeks)
1234 Support Markdown in source editor 1
8475 Support Markdown in WYSIWYG editor 2
9876 Test rendering of all supported Markdown syntax 1
5555 Conduct closed beta and collect feedback 1

4.1 Deliverables

What are the concrete outputs of the completed implementation? List each one here. These are similar to success criteria, but nail down what specifically will be produced by the implementation effort.
  • Code changes to enable Markdown rendering and authoring
  • User documentation for use of Markdown

4.2 Followup work

When appropriate, include some information about what "next steps" may be after the design is implemented. For example, if your design covers the initial implementation of a feature, there may be followup work to implement some additional "power user" functionality which would be detailed in a separate design document.

5 Revision History

As this document evolves over time, write down any significant changes to the design document that are made. This enables the document's readers to understand how the document has changed.
 Date   Username   What changed
 2020-01-01   joelthor   Added requirements to support non-technical users not having to understand or learn Markdown.