Writing a design document (RFC) that reviewers can decide on

Goal

Have a larger change decided by the people who will have to live with it, based on a document that can be read in twenty minutes, and before anyone writes the code. Later, the same document serves as a record of why the system looks the way it does.

Prerequisites

A change that is too large or too contentious for a pull request description; known reviewers with the authority to accept it; a place next to the code (a docs/rfcs/ directory, a numbered file, a pull request). PEP 1 and the Rust RFC template are public examples of such processes. The documentation chapter of "Software Engineering at Google" states that the templates used there require considering security, internationalization, storage requirements and privacy, and that these parts are usually reviewed by specialists in the respective area.

Steps

1. Describe the problem before any proposal: who is affected, what happens today, which constraint forces a change. If the problem cannot be stated in one paragraph, the document is not ready.
2. List goals as numbered, verifiable statements, along with non-goals that limit the scope. Non-goals keep the review from sprawling into adjacent requests.
3. Explain the proposal twice, as the Rust template prescribes: once at user level (what the change looks like to users), once at reference level with precise semantics, formats and edge cases.
4. Record the alternatives that were considered and why each was rejected. PEP 1 calls for a section on rejected ideas, with reasons, so that the same idea is not raised again; the Rust template has "Rationale and alternatives" for this.
5. Name the drawbacks, compatibility consequences, migration and rollout, and operating costs honestly; a document without drawbacks reads like advertising.
6. Close with open questions, split into "must be decided in this review" and "can be resolved during implementation".
7. Distribute it with a deadline for review, answer comments in the document rather than in chat, and record the outcome in a status line (draft, accepted, rejected, superseded). Keep rejected documents: they answer the next person who comes up with the same idea.

Expected result

Reviewers argue about the problem and the trade-offs, not about missing context. The accepted document becomes the reference for the implementation and, as the cited Google chapter suggests, at launch it becomes the yardstick for whether the stated goals were met.

Limits and test basis

A design document is not a specification; details change during implementation, and the document should say which parts are binding. For small changes, the ritual costs more than it delivers. The structure follows the cited templates; an effect on decision quality has not been measured here.