Docs
Design doc (RFC) template
A technical proposal with context, the design, alternatives you rejected and a rollout plan, open for comments.
RFC 014: move search to Postgres full-text
Summary
Context
Proposal
tsvector column on pages, weighted title A, body Bselect id, title,
ts_rank(search, query) + similarity(title, $1) as score
from pages, websearch_to_tsquery('english', $1) query
where search @@ query or title % $1
order by score desc
limit 20;Alternatives considered
Keep the cluster and fix the reindex
Hosted search API
Risks
Rollout
Open questions
What it is
A design doc, often called an RFC (request for comments), is a technical proposal written before the build. It gives the context, the proposed design, the alternatives you rejected and why, the risks and a rollout plan. It has a comment deadline and a named decision maker, so the discussion ends with a decision.
When to use it
- Changes that affect several services or teams
- Choosing between two or more technical approaches
- Anything that's hard to undo once shipped
How to use it
- 01
Set the deadline
Fill in the status callout with the comment deadline and who decides.
- 02
Show the design
Use code blocks with a language for schemas, queries and config. Keep diagrams as image links.
- 03
List what you rejected
Put each alternative in a toggle with the reason. Reviewers will ask about them anyway.
- 04
Record the decision
When it's decided, add a row to the decision log and link this doc with @.
Or have the AI draft your version
"Write a design doc proposing a move from cron jobs to a job queue for sending emails, with context, the proposal, two alternatives, risks and a four-step rollout."
Related templates
All templatesDocs
Product requirements doc (PRD)
Problem, users, requirements by priority, success metrics and open questions for one feature.
Docs
Decision log
Every decision with date, owner, status and the reasoning, so nobody has to ask why six months later.
- How the AI works
Draft your own with AI
Describe the page you need in one sentence. The AI writes it, and you edit it like any other page.