Design Docs, RFCs and Writing Things Down

In Lesson 1 and 2 you saw small decision notes. This lesson is about the bigger written plan: what goes in it, how real projects structure it, how to get feedback without endless arguments, and when not to write one.

Start with Lesson 0 for the six-step answer shape. A design doc is that same shape, written down.

Everything here is common practice and opinion. Teams differ. Use the ideas, not the exact words, and always use your own true examples.

Words used in this lesson

• A design doc is a short document that explains a plan: the problem, the proposal, the other options and the risks. You write it before the work.
• An RFC (Request for Comments) is a design doc that is shared for comments from a wider group, with a decision at the end.
• A KEP is Kubernetes' name for an enhancement proposal. A PEP is Python's name. They are RFCs with their own rules.
• Goals and non-goals. Goals are what the plan must achieve. Non-goals are things you will not do, written down so the discussion stays focused.
• Alternatives are the other options you considered, and why you did not choose them.
• Prior art is how other teams or projects solved the same problem.
• Rollout and rollback are how you release the change in steps, and how you go back if it goes wrong.

Why write it down

The long reading lists that many engineers use agree on a few simple reasons (I summarise what the lists say about each article):

• Writing is cheaper than building. One article in the list says a few days of design writing can save weeks of wasted implementation, because writing exposes a flawed design early.
• A written memo forces clearer thinking than slides. Another says slides hide how ideas connect to each other; sentences do not.
• A document culture helps everyone join in. An article about Amazon's document culture says written documents reduce bias and avoid audio and screen-sharing problems in meetings.
• People review at their own time. A reader in another time zone can think before they answer.

What real projects put in the document

Three public templates, side by side. They are different sizes, but you can see the same bones.

Two things stand out. Every one of them has a place for why not (drawbacks, alternatives, rejected ideas). And the biggest project (Kubernetes) adds a production readiness check: can we see it, scale it, support it and roll it back?

A small-team design doc (my own mix)

For one team, one page is often enough. Use these headings and keep each part short:

# Title: the decision, not the problemStatus: draft | in review | accepted | rejected | withdrawn | replaced by <link>Owner: <name>     Reviewers: <names>     Decide by: <date>## Summary            (3 sentences)## Problem            (who is hurt, how much, how do we know)## Goals / Non-goals  (what must be true / what we will NOT do)## Proposal           (how it works, with one small example)## Alternatives       (at least two, and why not)## Risks              (what could go wrong, how we reduce each)## Rollout / rollback (steps, flag or switch, how to go back)## Test and monitoring plan (how will we know it works)## Open questions

The status words come from Python's PEP process: Draft, Accepted, Rejected, Withdrawn (the author dropped it or chose another), Deferred (stalled, can come back), Final (done), and Superseded (replaced by a newer one). Using clear status words stops people asking "is this still true?".

A simple process that works

1. Talk first. Have a short chat with one or two people before you write. The Rust process says the same: discuss the idea informally before you write the RFC.
2. Write a short draft and name one owner and the reviewers.
3. Set a date. Give people a fixed time to comment (Rust's "final comment period" is ten calendar days, see Lesson 2).
4. Answer every comment, even with "noted, not now". Change the document, not only the chat.
5. Decide. Python's PEP rules say one body has the final say (the Steering Council, who can delegate a single PEP to a person). In a team, say who decides before you start. You do not need everyone to agree, but write down the reasons.
6. Record the outcome and the rejected ideas. Link it from the pull requests.

Writing tips from the lists

The reading list has a small writing section. In simple words:

• Cut words. George Orwell's six rules (cut unnecessary words, prefer the active voice, avoid jargon) apply to design docs too.
• Be specific. One article says swap general words for specific ones: "slow" becomes "p95 of 2.3 s".
• Short sentences, active voice. This is the advice of Google's "Technical Writing One" course, as the list describes it.
• Start with the answer. Put the decision and what you need from the reader at the top.
• Show an example. The Rust template asks you to teach the idea "as if it were already part of the language". A tiny example makes a plan real.

Interview questions

Key takeaways

• Write the plan before the work when the change is big or hard to undo. Skip it for small, local, reversible work.
• A good doc has: problem, goals and non-goals, proposal, alternatives, risks, rollout and rollback, how you will measure success, open questions.
• Always include "why not" (drawbacks, alternatives, rejected ideas). It stops the same debate from returning.
• Use clear status words: draft, accepted, rejected, withdrawn, replaced.
• Name an owner and a decider, set a date for comments, answer every comment, then decide.
• Write short, specific, active sentences, with the answer first.
• This is common practice and opinion. Adapt it to your team.

What's next

Next: Technical debt, quality and the rewrite trap, Lesson 6. Practise: take one decision from your last project and write the one-page doc as if you were starting today. Notice how hard it is to write the "alternatives" and "risks" parts honestly.