The Danger of Design Docs
It is very common for engineers to write a “design doc” before starting every major project. Unfortunately, it also very common for these documents to be long, convoluted, and generally hard to read. There is a good reason for this muddiness – over the course of the lifetime of a project idea, it goes through many different reviewers with different needs.
The way to write a clear design doc is to separate it into a progression of distinct parts and ideally each as a separate document
that each have the goal of advancing the project:
- The Problem statement, where we answer “what is the next impactful problem for us to explore”
- The Product specification, where we answer “given this problem, what is the product-level solution”
- The Proposal for implementation, where we answer “given this product-level solution, how do we implement it”
- The Project plan, where we answer “given this implementation, where should we start and how do we know that we’re done”
Problem statement
The first document to write During the consensus building phase
is the problem statement. The goal of the problem statement is to answer the question “what is the next impactful problem for us to explore.” see Working Backwards on the PR/FAQ for how Amazon views this problem
At this stage, the target audience is business users who assess the value risk of “will the customer buy it” see Empowered on Risks for more on value risk
.
The SCQA for this document would be:
| S | We have available resources |
| C | We have many different opportunities |
| Q | (What opportunitity should we do next?) |
| A | ___ is a very impactful opportunity because ___ |
Common things to include at this stage:
- Target market
- Current approaches
- Known customers requesting this
- Opportunity cost of not doing this
Advice for this stage
- It is rarely appropriate to talk about proposed solutions at this stage.
Product specification
Having identified that we should explore a given problem space, the next document to write is the product specification. The goal of the product specification is to answer the question “given this problem, what is the product-level solution.” A product-level solution describes the end-to-end experience for users.
At this stage, there are 2 target audiences:
- Business users who assess if the proposed product-level solution will address the problem and will be usable by our customers see Empowered on Risks for more
- Engineers who assess the technical feasability of the product-level solution
The SCQA for this document would be:
| S | We know this is a problem for customers |
| C | We want customers to want to use our solution |
| Q | (What do our customers actually want?) |
| A | As a ___ , I want to ___ so that I can ___ |
Common things to include at this stage:
- Target users
- Initial use cases
- Out-of-scope use cases
- How will we quantify value?
Advice for this stage
- It is rarely appropriate to talk about implementation at this stage.
Proposal for Implementation
Having identified a product-level solution, the next document to write is the proposal for implementation. This is the start of the design phase
The goal of the proposal for implementation is to answer the question “given this product-level solution, how do we implement it.”
At this stage, the target audience is engineers, who want to assess the feasibility risk of building it.
The SCQA for this document would be:
| S | We want to build this product-level solution |
| C | We need to implement it in our existing product |
| Q | (What is the best way to implement this solution?) |
| A | We will make these changes to our system: ___ |
But be careful to avoid the intellectually blank statement here
Common things to include at this stage:
- What are the major systems that will change?
- Who is needed (what people, teams, roles, skills, etc)?
- What resources are needed?
- What dependencies on other projects are there?
- What ongoing maintaince will be required after we do this?
- How will we monitor it?
- What alternatives did we consider?
Advice for this stage
- “Nouns and Verbs” or “Life of a request” are powerful tools to identify the major systems that need to change
Project plan
Finally, an implementation is only useful if we actually do it. The final document to write is the project plan, with the goal of answering “given this implementation, where should we start and how do we know that we’re done.”
At this stage, the target audience is engineers, who will want to know what work to do.
The SCQA for this document would be:
| S | We know what we want to implement |
| C | We want to minimize risk of failed execution |
| Q | (What actions should we take in what order?) |
| A | We can hit the goal ___ by hitting this sequence of intermediate goals: ___ |
Common things to include at this stage:
- A great goal
- Deliverables
- “Who will do what by when”
- RACI matrix
- Plans for rolling out the project and integrating it into customer’s processes.
Advice for this stage
- Aim for simple wins early to create pyschological momentum
- Aim for complex or risky milestones early to pro-actively reduce uncertainty
- Aim for as short of milestones as possible and the be able to show these milestones to customers. Weekly milestones generally work best, but it be careful – “a project is always at risk of being delayed by the duration of its longest milestone” one of Horstman’s Laws of Project Management
.