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
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