Technical design doc template
A design doc is how an engineer gets a big change reviewed before building it. Written well, it saves weeks of rework. This template is structured to get useful feedback fast, with the questions reviewers always ask already built in.
Updated
The short answer
A technical design doc, often called an RFC, describes a significant engineering change before it's built: the context, goals and non-goals, the proposed design, alternatives considered, risks and the rollout plan. Share it for review early, and record the final decision so future engineers know why the system works the way it does.
Pastes with formatting into Google Docs, Word, Notion and Confluence.
[Title]: technical design
Author: [name] | Reviewers: [names] | Status: Draft / In review / Approved / Superseded Epic: [link] | Last updated: [date]
1. Context
What exists today and why it needs to change.
2. Goals
-
3. Non-goals
-
4. Proposal
How it will work. Include a diagram for anything with more than two components.
Data model and APIs
Failure modes
What happens when each dependency is slow or down.
5. Alternatives considered
| Option | Pros | Cons | Why not |
|---|
6. Risks and open questions
| Risk or question | Impact | Owner | Plan |
|---|
7. Rollout
- Migration steps:
- Feature flag:
- Rollback plan:
- How we'll know it works (metrics, alerts):
8. Decision
| Date | Decision | Decided by |
|---|
Example: fictional Meridian Labs data
Streaming aggregation: technical design
Author: Ines Batra | Reviewers: Mila Karlsen, Tom Reyes, Avery Nolan | Status: In review Epic: Streaming aggregation | Last updated: 26 Sep 2026
1. Context
Dashboards read from nightly batch tables, so numbers are up to 24 hours old. Self-serve dashboards (15 Nov) needs figures under 5 minutes old.
2. Goals
- Aggregates for the top 20 metrics under 5 minutes old
- No double counting when consumers restart
3. Non-goals
- Real-time alerting
- Changing the event schema (owned by the data platform team)
4. Proposal
Consume events from the Live event pipeline, aggregate into 1-minute windows, and write to a rollup table that the Dashboard builder reads.
Data model and APIs
rollup_minute(metric_id, team_id, window_start, value). Dashboard builder reads through the existing metrics API.
Failure modes
If the pipeline is slow, dashboards show the last complete window with a "data as of" time.
5. Alternatives considered
| Option | Pros | Cons | Why not |
|---|---|---|---|
| Hourly batch | Simple | Numbers up to an hour old | Misses the 5-minute goal |
6. Risks and open questions
| Risk or question | Impact | Owner | Plan |
|---|---|---|---|
| Event schema contract is 4 days overdue | High | Avery Nolan | Build against the draft schema behind a flag |
| Metric ownership unclear | Medium | Avery Nolan | Aggregate only catalogue-approved metrics |
7. Rollout
- Migration steps: backfill 30 days of rollups
- Feature flag: streaming_rollups
- Rollback plan: switch the flag off; dashboards fall back to batch
- How we'll know it works (metrics, alerts): lag under 5 minutes, alert above 15
8. Decision
| Date | Decision | Decided by |
|---|---|---|
| 26 Sep 2026 | Proceed with 1-minute windows | Mila Karlsen, Ines Batra |
New to design docs? Start here
What it is
A technical design doc is an engineer's written plan for a significant change, shared for review before building. It catches expensive mistakes while they're still cheap to fix.
Use it when
- The work will take more than two weeks
- It affects other teams or systems
- It would be expensive to undo
Who writes it
The engineer leading the work
Who reads it
Senior engineers, affected teams, and the product manager for scope
How to fill it in
- 1Context
- Enough for a reviewer from another team to follow. Link to the product brief for the "why" instead of repeating it.
- 2Goals and non-goals
- Non-goals stop the review turning into a debate about everything the system could do.
- 3Proposal
- Lead with the simplest description that works, then the detail. Always cover failure modes.
- 4Alternatives considered
- Reviewers will ask "why not X?". Answer it before they do.
- 5Risks and open questions
- Anything that could make the design fail or that reviewers need to weigh in on, each with an owner and a plan.
- 6Rollout
- How it ships safely and how you'd undo it. Many designs fail here, not in the architecture.
- 7Decision
- Record the outcome and who made it. This is what future engineers will search for.
How to run a design review
- Share the doc at least two days before any meeting, with the specific questions you want answered.
- Collect comments in the doc, then meet only to resolve disagreements.
- Mark the status clearly, and change it to Approved or Superseded when that happens.
Design doc or ADR?
A design doc explores a significant change before it's built. An architecture decision record (ADR) is a short, permanent note of one decision: its context, the decision and its consequences. Many teams write a design doc, then record its key decisions as ADRs.
Design doc in a wiki
- Loses track of the epic it was written for
- The final decision gets buried in comments
- Nobody knows if it's still current
Design doc in Ondule
- Linked to its product and milestone, with their live status
- Decisions recorded as real records, searchable later
- Readers see what shipped next to what was proposed
How to do this in Ondule
Questions
- What is the difference between a design doc and an RFC?
- Mostly the name. Both propose a significant change for review. "RFC" (request for comments) emphasises the review process.
- When do you need a technical design doc?
- For changes that take more than a couple of weeks, affect other teams, or would be expensive to undo.
- How long should a design doc be?
- As short as the change allows. Two to five pages is common. Put detail in appendices.