---
tags: development process, wip
---
# [WIP] Design Doc/Enhancement Proposal Process

The design process can be long winded and difficult. This document lays out how we ought to approach our design tasks aiming to get them completed with a high degree of quality/correctness and as de-risked as possible.

### Goals

1. Get designs out asap
2. Reduce any risk of "building the wrong thing"
3. Improve planning and reduce splippage by continuously polling and reviewing designs and agreeing on next steps

### Process

Given work that requires design front-loading (e.g. epics, features, bug fixes, etc.):
1. Decide how many people to involve. We should try to typically involve at least two people: one accountable, but all responsible. For most design docs/enhancement proposals, two should be the norm.
2. Time box the design for an agreed period of time.
3. We can agree on a design doc template, but I think the EP one covers most areas. We should also identify the stakeholders (internal/external) and include them in the review meeting.
4. Once the time box elapses, organize a meeting: team (optional) + stakeholders (required) + at least one principle or staff engineer (required) + authors (at least 1 required).
5. The meeting request should include the document to be reviewed. At the end of the review meeting, the authors should have enough feedback to decide whether the design is done (just needs polish) or is more time is needed. If so, go back to step 3.
6. Address comments, break down the epic into tasks/stories and schedule them for refinement for sizing.

If we're talking about an enhancement proposal we have two options:

1. Have the review during the work group meeting
2. Once it's accepted through an internal review post the enhancement proposal PR to the email group, set a time frame for collecting async feedback from the community, address any feedback and merge.

**NOTE**: If we need to iterate on the design and need to do so *now*, we can rejigger the sprint plan to ensure we're not over capacity

### Review Meeting Format

**Attendants**:
- At least one of the authors (they should be able to answer questions about the design and defend it)
- At least one of principal or staff eng: to provide guidance
- The required stakeholders (e.g. PM, customer or team representative, subject matter experts, anyone with "skin in the game")
- OLM Team members - if you're not required, you are optional

**Duration**: Typically 1.5 hours, but can be longer for longer documents. Exercise your judgement. If in doubt, make it 2 hours. We can always finish earlier.

**Agenda**:

Here are the typical steps for a design review meeting:

**Introduction (5 minutes)**
Introduce the topic/problem in a few sentences + highlight any areas you feel are more important to be reviewed. Or any instructions you feel might make the process more valuable to you and help reviewers give the best possible feedback.

**Silent Reading (30 mins)**
Everyone reads through the document. Add comments as you go.

**Discussion (50 mins)**
Once everyone has finished reading, get overall impressions and then step through the comments and address each of the issues.

**Action Items (5 mins)**
Agree on a series of action items that will take this design to completion. Could be as simple as "spruce up this section here", to "we need a new design because of xyz"

The duration for each step of the agenda can very depending on the size/nature of the document. But, this should be a reasonable time allocation.

### Justification

**Why more than one person per design doc?**
If you have at least two people working on it, we may be able to speed up the writing and review process. We also gain redundancy in case of absence, shifting priorities, etc. We can also use this as an opportunity to include more junior member and expose them to the process. We can also use this as an opportunity for knowledge sharing by pairing a domain expert with someone who isn't.

**Why timebox?**
We should estimate a reasonable amount of time to get it completed and iterate. This keeps things flowing and gives us the opportunity to pivot to something else, or throw more resources at it early. For upstream, we can choose our own adventure:
1. Do the design + review round internally first (get it gud) then kick it upstream for a time-boxed comment period (e.g. 1 week). Allow people to ask for more time if necessary.
2. Do the review round in the work group meeting. It will probably take the whole meeting. So, an ad-hoc community meeting is also a possibility.

Personally, I'd go for 2 since it schedules the community feedback and makes the timeline more predictable. But it may well be that different options are better applied to different design tasks.

**Why is the review meeting like this?**
We all need to sit down and read the docs anyway. So, let's do it together. This gives us the opportunity to discuss any issues, sync, and figure out the next steps. There's no async period of waiting for comments. You can know exactly when to expect feedback. Makes planning a whole lot easier.