Skip to main content

Design Documents for Small-to-Medium Features

What This Concept Is​

A design document (design doc) is a short, pre-implementation write-up that answers, for a specific feature or change:

  • What are we building? (scope, non-scope)
  • Why are we building it? (problem, goals, non-goals)
  • How will we build it? (approach, interfaces, data model)
  • What else did we consider? (alternatives)
  • What will go wrong? (risks, rollback, open questions)

For small-to-medium features (a week to a month of work), this is usually 2-6 pages -- not a thesis, not three bullet points. Long enough to force thinking, short enough that teammates will actually read it.

Why It Matters Here​

A design document is the cheapest place to discover that your design is wrong. Code found wrong is a refactor; design found wrong in a doc is a delete key. The doc also:

  • recruits reviewers before implementation so their feedback is cheap
  • creates shared context so the PR is small and easy to review
  • pairs with ADRs: the doc covers the feature, the ADRs cover the sharp decisions inside it
  • becomes the answer to "what did we try last year?" when a similar feature comes up

Concrete Example (outline)​

# Design: Promotions Service v1

Author: Jutta  |  Status: Draft  |  Reviewers: @maya @dan

## 1. Summary
Add a Promotions service that applies time-bounded discount codes at
checkout, usable from the web and mobile clients.

## 2. Goals / Non-Goals
Goals:
- support percentage and absolute-amount codes
- enforce time and usage limits
- emit one audit event per application
Non-goals:
- tiered loyalty discounts (tracked separately in LOYALTY-12)
- non-checkout uses (e.g. in-email previews)

## 3. Background
Today the checkout service hardcodes two seasonal codes. Marketing needs
weekly campaigns without engineering involvement.

## 4. Proposed Design
- A new `promotions` service behind `/promotions`.
- Checkout calls `POST /promotions/apply` with `{cart_id, code}` and
  receives an adjusted total plus audit id.
- Storage: Postgres (per ADR-0007), tables `promotion` and `promotion_use`.
- Concurrency: per-code redemption counter uses `SELECT ... FOR UPDATE`.

[Sequence diagram showing: client -> checkout -> promotions -> db]

## 5. Alternatives Considered
A) Extend checkout instead of a new service.
   Rejected: checkout is already overloaded; promotions lifecycle differs.
B) Firestore instead of Postgres.
   Rejected: ADR-0007 standardizes on Postgres; no Firestore ops experience.

## 6. Risks and Open Questions
- Abuse: users trying codes across accounts. Mitigation: rate limit per IP,
  tracked in RISK-04.
- Rollback: feature flag on checkout; DB migration is additive.
- Open: do we support combining two codes? (default: no for v1)

## 7. Rollout Plan
Week 1: implement promotions service behind a flag, shadow-call from checkout.
Week 2: enable for 5% traffic, monitor error rate and redemption latency.
Week 3: ramp to 100%, remove flag.

Common Confusion / Misconception​

"Design doc = book." If you cannot write it in six pages, the feature is either too big or not understood yet. Break it up or clarify the problem first.

"Design doc = code outline." It is not a file-by-file prospectus. It is a conversation about what and why; file layout belongs in the implementation PR.

"Design doc = ADR." A design doc describes a feature; it may contain or reference several ADRs. ADRs are atomic decisions; design docs tie them together.

"Design doc = diagram." One good diagram is worth its weight, but a design doc without prose leaves no room for trade-offs. Diagrams show structure; prose shows reasoning.

"Non-goals" is the most-skipped section. It is also the most valuable. Every non-goal is a promise you will not silently scope-creep into.

How To Use It​

For any feature larger than roughly a week of work, write a design doc before the first real line of production code. Use the outline above; keep each section short; finish with open questions. Then:

  1. Share the doc with at least two reviewers.
  2. Let comments simmer for 24-48 hours.
  3. Resolve all must-discuss comments before starting the PR work.
  4. Link the doc from the first PR ("Implements design doc promotions-v1").

For smaller features, a single-page design doc is still useful; it keeps you from over-extending a pattern.

Check Yourself​

  1. What is a non-goal, and why is it worth writing down?
  2. Why is a design doc cheaper than a PR to change direction in?
  3. When does a design doc need an ADR inside it?

Mini Drill or Application​

For a feature you are building this semester (real one), draft a two-page design doc using the outline above. Include at least one alternative considered and at least one open question.

Read This Only If Stuck​