Design docs are a way to propose future work and get detailed technical feedback.
Brief description of what the problem or opportunity is. Give an overview of the domain and pain points. What is the current solution? Give some details about what its shortcomings are.
Give a high-level summary of your proposed solution. This should explain what it will do, how it will be built, and what’s different. Explain the advantages of your proposal here.
Go over the goals of the project. Explain the requirements and outcomes you expect in bullets:
- requirement/impact
- requirement/impact
- requirement/impact
[optional] if there’s anything you’re not trying to do, mention it here. For instance, if you’re refactoring for dev velocity and not performance wins you might want to clarify that:
- non-goal
- non-goal
Give an overall summary of the design and major pieces. A diagram may be helpful for the reader here to understand the top-level view.
Give the reader context on relevant design details like the major request paths and data model you’re proposing. You may need to add sections for each major component to explain the design, feel free to add them.
What were the other solutions you considered? Why weren’t they chosen? Useful for discussion but also to serve as documentation so these alternatives aren’t considered again.
List any open questions that you’d like to discuss that still need to be ironed out:
- Question1
- Question2
[optional] If this is a collaboration, include the names of other relevant engineers that will be key to the project's success. If the work will be split up, identify who will be working on each part.
Add high-level timelines and key milestones for tracking project execution.
Space for you to add any relevant links or detailed figures that you didn’t want to inline.