Design Doc Template
A structured recipe for writing technical design documents that align teams and surface tradeoffs before code is written.
Overview
Every feature at Meridian starts with a design doc. This template forces the author to state the problem, enumerate alternatives, and justify the chosen approach with data. It is lightweight enough for a two-hour spike but thorough enough to prevent multi-week rewrites.
Sections
- 1. Context & Problem
One paragraph on what triggered this. Link the Linear ticket, customer report, or perf trace. State the problem in terms of user impact or system constraint.
- 2. Non-Goals
Explicitly list what this doc does NOT cover. Prevents scope creep during review.
- 3. Proposed Solution
Architecture diagram, data flow, API contract. Include a sequence diagram if the change spans services.
- 4. Alternatives Considered
Table with columns: Approach, Pros, Cons, Why Rejected. At least two alternatives.
- 5. Rollout & Rollback
Feature flags, migration steps, monitoring dashboards, and the exact command to revert.
- 6. Open Questions
Unresolved decisions that need input from specific people. Tag them by name.
Example
# Design Doc: Async License Validation
## Context
Customers on spotty connections see 12s timeouts during Nimbus startup. The synchronous HTTP call blocks the UI thread.
## Non-Goals
Offline mode, grace-period caching (separate doc).
## Proposed Solution
Fire-and-forget validation on a background thread. UI proceeds with last-known-good state. If validation fails, surface a non-blocking toast and schedule retry with exponential backoff.