Running an async review: ask for the feedback you want, close on a date

The win for today: the DocuDex design doc — now with POC results, two ADRs and two diagrams — sent for review with a five-line header that says what feedback you want, who decides, and when it closes; then, a week later, a written review outcome. About thirty minutes now and thirty when the comments are in. This is the lesson the tech-lead role is actually testing.

What to do (read this first)

1. Put the five-line header from the review request reference at the top of the DocuDex doc. Fill every line.
2. Choose reviewers. For a solo project with no senior peers to hand, the review is public: r/golang, the Go Forum (forum.golangbridge.org) and Gophers Slack #tools, all pointing at one public URL for the doc, ADRs, POC and diagrams so comments land in one place. No approver — say so in the header; you are the decider and everyone replying is input. One post text, written as the "wanted" line, one close date for all three.
3. When comments arrive, sort every one into challenge / gap / evidence / preference / nit before replying to any. Answer challenges and gaps in the doc, then point to the doc from the thread.
4. On the close date, write the Review outcome section and send one broadcast message. Change the status.

1. What the process is for (4 min)

Ubl's Design Docs at Google describes review as comment threads on the doc, and gives the reason it exists: to bring the organisation's experience to bear "early, before expensive changes become necessary". The review is not a gate; it is the cheapest moment to be wrong.

Sourcegraph's handbook adds the two things that make it work asynchronously: a status label that tells reviewers what kind of reading to do ("Reviewing problem" means "confirm the problem definition is correct"; "Reviewing solution" means the problem is agreed), and named roles — "the decider, input providers, approvers" — plus tags for teams that are affected. HashiCorp's writing practices add the order: the author's own team reviews first, named approvers sign off, and then the decision is broadcast to the company. The Rust RFC process contributes the close date: a final comment period after which the decision stands.

Put together, that is the five-line header in the reference. Nothing in it is clever; all of it is routinely skipped.

2. Triage the comments (6 min)

These are comments the DocuDex doc could plausibly get. Sort each.

3. Ask precisely (3 min)

4. Do it (30 min now, 30 later)

Now: write the header on the DocuDex doc; link the ADRs, the POC write-up and both diagrams from it so a reviewer has one entry point; pick the reviewers and send it.

Public replies skew to preference and evidence rather than challenge; that is what the triage table is for. Do not argue in any thread — answer in the doc, reply with a pointer. Three channels with one close date produce one review outcome, not three.

On the close date: triage, answer in the doc, write Review outcome (what changed, what was raised and not changed and why, the status line), send one broadcast message, change the status.

5. Retrieval (2 min)

Two of these are from earlier lessons.

Read next

HashiCorp's Writing practices and culture — ten minutes — for the team-first → approvers → broadcast order, from a dev-tools company that runs on it. Then re-read Sourcegraph's RFC page with the header in front of you.