Design Document / RFC

Description

Write a short structured proposal (context, goals, design, security and privacy, alternatives) and circulate it for comment before building, using a template and a pitfalls checklist.

Many people cannot share an understanding of a feature, product plan, API or process until it is written down. A design document, often called an RFC, does this before work starts. Reilly's minimum headings are context (title, author, dates, status), goals stated without implementation detail, the design in enough detail to judge whether it will work (diagrams, data models, wireframes, process steps), security, privacy and compliance, and alternatives considered including prior art and in-house options. Optional sections cover background, trade-offs, risks, dependencies and operations. Authors self-check against pitfalls such as 'every user just needs to', postponing the hard part, or a disguised rewrite, and write concretely: being wrong is better than being vague. Reviewers match depth to the stage, explain their reasoning, label importance and ask whether the work should exist at all, whether it solves the problem and whether it fails safely.

Attributes

Loss type
Active
Effort
Days

Steps

  1. Use the organisation's template if one exists; otherwise include the minimum headings.
  2. Context: title, author, created and updated dates, and status (idea, open for review, superseded, implementing, done, on hold).
  3. Goals: the problem or opportunity and why it matters, with no implementation detail.
  4. Design: how the goal will be met, with whatever readers need (flows, wireframes, diagrams, data models, dependencies, costs).
  5. Security, privacy and compliance: what needs protecting and what user data is touched, or why the section does not apply.
  6. Alternatives and prior art, including off-the-shelf and in-house options; send the document to owners of any in-house option not chosen.
  7. Self-check against the pitfalls list, then circulate for comment with a deadline; reviewers label the importance of each comment.
  8. Record decisions and update the status as work proceeds.

Sources

  • The Staff Engineer's Path (Reilly, 2022)

Also known as

  • Design document / RFC (request for comments) with template and review
  • RFC
  • Request for comments
  • Design doc
  • Technical design document
  • Design proposal

Categories

  • Design
  • Design & Product Practice