-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Design Docs
What problem are we trying to solve and how do is this tied to our business objectives? Why do we think this particular feature is going to further the objectives?
For the feature, are there specific goals we want to meet, and non-goals that we have decided we do not need to address?
There is almost always more than one way to solve a problem. What alternatives were considered? Why did we choose the approach in this doc? This section is important to ensure we have done due diligence and considered alternatives. We would often look at space/time tradeoffs here, or constraints imposed by existing architecture or resulting from dependencies outside of our control.
What is the high-level architecture of the proposed solution? This is a good time to make sure we are not over-engineering and subscribing to pattern-itis. We can typically describe the architecture primarily in the form of one or more diagrams. See the C4 model for a good way to do this. Note that for a simpler component this section may not be required.
If this new work exposes public APIs for consumption by others, document them here. Note that the APIs may be emergent (TDD can help with this), so this section may be updated later, unless delaying the final design of the APIs would be blocking clients of the APIs, in which case we may need to front-load the work in this section. Sometimes APIs are documented separately in reference documentation, but it makes sense to start with the design doc while the API is still being agreed on.
Discussion of novel algorithms used or designed, cryptography usage, threat model, privacy (including use of PII), scalability, resource requirements, etc.
How will we measure success of the feature? Are there experiments we want to conduct that we need to account for during implementation? What telemetry might we need? Are we going to want dashboards for product health and feature usage, and will we have the data for those?
How will the feature be tested? Where are the right “seams” for unit testing? Are there integration test concerns? Will manual testing be required, and who will carry that out at what cadence? How will coverage data be collected and processed?