Design doc template

XYZ Design

Author: [email protected]
Contributors: abc@, ….
Last updated: 10th March 2023
Status: [Draft, In Review, Approved]
Approvers: Security, Tech [At least one security approver is necessary]

Context

This document describes the high level design for . Provide more context here for the component. For context on why a structure for design docs is useful please refer to this excellent write up.

Goals

What is being designed, for which requirements/constraints.

Non-goals

If it is worth mentioning then explicitly mention what things are explicitly not being considered as part of this design e.g. This design does not provide a solution for modeling use case EFG since that is out of scope and not a priority at this moment.
Background
Links to PRD or other reference material that can be useful or required for the readers before diving in further. Call out explicitly if something is a must read.

Glossary

Define terms the reader may not be familiar with. Domain specific terms, acronyms, terms in use internally at your company etc all go here.

Overview

A brief overview of the document goes here
Can be a summary of sorts, the details for which can be found by the user in the Details section below
It can also provide the reader a structure to expect ahead in the document
It can capture a high level diagram that is fleshed out in more detail later
Details
All details go here. Given the unique nature of each design details can vary so use your imagination when it comes to structuring this section.
Add separate subsections as needed e.g. one for API, one for storage.
Block diagrams, sequence diagrams etc all go here. Please use Google Diagrams (Insert > Drawing) for consistency, easy sharing and viewability.
A separate subsection for β€œAlternatives considered” can also be added for each design decision.

Security considerations

How are bad actors kept out?
Authentication, authorization, encryption mechanisms used.
Above can be between different company system components or between company and its partners.

Privacy considerations

Detail out the steps taken here for protecting the user’s privacy. Note that privacy is different from security. A trusted party may still be forbidden from looking at PII or SPII. If there is any additional data collection it should be covered here. Design to provide Transparency / control of data, access to the aforementioned data, logging, and auditing of access should also be covered in this section.

Data Localisation

We need to abide by data localisation norms set by the government. This means that all our user data needs to be stored at rest only in India. Processing of data outside India may be allowed but even it should be called out here, discussed widely and agreed upon before implementing. This section exists here to act as a reminder.

Test & Rollout Plan

Integration tests

Add what integration tests will help test this design

QA Plan

Any support needed from the QA team for testing should be covered here. Especially if there is something out of the ordinary, e.g new kinds of devices, specific telecom providers, bad connectivity testing etc can be covered here.

Load Testing

For infrastructure changes it is a good idea to add load tests in the plan so that system performance can be tested on a regular basis and any regressions can be caught in the testing phase

Rollout

Do we need to guard the new changes behind a flag and then switch on in production or will the changes be done without flags?
Is A/B testing necessary?
Does this need a percentage ramp up in production?
Is rollout gated on dogfood/friends and family testing results?
etc...

Metrics & Logging

What metrics will be collected and/or logged?
What is the expected bump in log data storage requirements?
Etc ..

Resource estimates

Estimates on additional compute, memory, storage, network requirements
Any additional requirements from devops team
Etc ...

Development Estimates

Rough estimates or a link to the broken down task spreadsheet goes here.

Open questions

During the design and review phase this section can be added to track open questions that the designers need answers to for finalizing the design.

Discussion notes

This section can contain any discussion notes that the designers feel can be attached for posterity and referred to from earlier sections in the doc.
Future Work