Design doc or technical spec.
Title of the design doc
author(s) and reveiwer(s)
date document was updated
High level summary that is 3 paragraphs max.
Description of the problem. Why necessary, what people need to know to properly asses this project, and how it fits into goals and strategies.
Goals should describe impact the completed project will have. Define metrics for success and show where those are being tracked.
Non-Goals are things that will "not" be addressed by this project.
List measurable checkpoints that others can skim quickly to track progress. Try to use calendar dates for milestones.
Include "updates" to milestones if there are changes.
High level example of how the current solution works. Great spot for user story.
Work through a user's story. Start with the high level view then fill in with lots of details. This should be enough information for someone else to implement the new solution for you.
Discuss other solutions. List some pros and cons of these alternatives.
Think about this now and not later. Your future self will thank you, when something breaks or under performs.
- How will this increase on call and dev-ops burden?
- How much money will it cost?
- Does it cause any latency regression to the system?
- Does it expose any security vulnerabilities?
- What are some negative consequences and side effects?
- How might the support team communicate this to the customers?
Reveal or discuss open issues that you are not sure about. Contentious issues that need others input.
This is at the end of the document. It is high detail for the engineers working on the project, tech leads, and their managers.
Breaking down how and when you plan on executing each part of the project.
Once the document is drafted start getting feedback.
Limit the time for feedback to avoid delays.
Take feedback and consolidate it into a list of points that can be reviewed and discussed more.