Design Docs
The design doc documents the high level implementation strategy and key design and architectural decisions with emphasis on the trade-offs that were considered during those decisions.
Design docs fulfill a number of functions in the software development lifecycle, such as:
- Early identification of design issues when making changes is still cheap.
- Achieving consensus around a design in the organization.
- Ensuring consideration of cross-cutting concerns like security.
- Scaling knowledge of senior engineers into the organization.
- Create an "organizational memory" around design decisions.
- Show the "big picture" within the "bigger picture"
- Help new team members ramp up faster
Design docs should not be “busy work”, but should be used appropriately to serve the needs outlined above. If there is an obvious and simple solution to a problem, it probably doesn’t need a design doc. If there are multiple alternatives and the choice is not obvious, or there are risks associated with any particular choice, it is worth documenting the decisions that were made and why.
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?