I run system design reviews, not process docs

Every team I have joined had a documentation problem.

The previous lead’s solution was always the same: write a process doc. Six pages on the wiki. “How we do code review.” “How we deploy.” “How we onboard.” Linked from a Slack pinned message nobody reads.

I stopped doing that. Now I run system design reviews instead. Two engineers, 45 minutes, one decision recorded in a markdown file. The process doc archive at every team I have led got smaller every year I was there. The systems got better at the same time.

Why process docs fail

Process docs are written for the writer’s anxiety, not the reader’s situation.

The writer is anxious that a future engineer will make a mistake the team has already made. So they write a doc that lists every step. The doc is comprehensive on the day it’s written. Six months later, three of the steps are wrong and nobody knows which three. The doc rots and nobody updates it because updating documentation is its own kind of unpaid work.

Engineers don’t read process docs to learn how the team works. They read commits, PRs, and the last time someone did the thing they’re trying to do. If the doc and the code disagree, they trust the code.

So you end up with two sources of truth, one of them lying, and the lie is the one nobody is allowed to delete.

What design reviews give you

A design review is not a doc. It is a 45-minute conversation between two engineers, before a non-trivial change, that produces three things: a shared understanding, a decision, and a short markdown file capturing the decision.

The format I run, almost without exception:

• 5 minutes context. What is the change. What’s already in place. Who else is affected.
• 15 minutes options. Two or three real choices. What each costs. What each absorbs.
• 15 minutes decision. Pick one. Write down why. Write down what could go wrong.
• 10 minutes “what could go wrong.” Failure modes. Rollback. Migration. Monitoring.

The output lives in tasks/specs/YYYY-MM-DD-<topic>.md. Not a wiki. The repo. Next to the code.

The doc is the decision, not the process. Two pages, sometimes one. Always dated. Always tied to a specific PR or set of commits that came after.

Why design reviews work

Three things.

They teach the rhythm of how the team thinks, not just what they know. A junior who watches three reviews internalises more about how the team makes calls than fifty pages of “this is how we approach things.” The “how” is in the conversation, not in the writeup.

They produce decisions, which age better than processes. A decision dated 2024-08-15 with a clear context still makes sense in 2026. You read it and know what was true at the time. A process doc with no date claims to be true forever and is wrong by Q3.

They scale to what actually changes. A 15-engineer team has maybe two non-trivial decisions a week. That is two reviews a week, two specs a week. After a year you have a hundred specs. That is the team’s memory in a form the team can actually search.

What about the boring stuff

People push back: “fine for big changes, but what about routine stuff like coding standards?”

I write those once, in a CONTRIBUTING.md next to the code, in 200 lines or fewer. Not because I think it’ll get read, but because the linter and the PR template should reference it. The linter does the work. The doc is the explanation.

The other thing nobody says out loud: most “process documentation” is one engineer trying to delegate decisions they don’t want to make. “When should we open a PR vs a draft PR” - decide it once, write it once, move on. If the rule needs ten paragraphs, the rule is wrong.

What it looks like in practice

The cadence is: when an engineer wants to make a non-trivial change, they post in the team channel and ask for a 45-minute review. We do them on a Miro board, screen-shared, with one engineer driving. The output is a markdown file in the repo’s tasks/specs/.

After three reviews, the new engineer runs one. After ten, they request reviews on each other’s work without me. That is the team having a memory. I did not write a single process doc to make that happen.