Skip to main content

Design Documentation Clinic

Produce three design artifacts for the same feature: one ADR, one mini design document, one sequence diagram. The goal is practice in writing little, communicating much.

Retrieval Prompts​

  1. What four sections are in a classic ADR?
  2. What belongs in a design doc that does not belong in an ADR?
  3. What question does a sequence diagram answer?

The Target Feature​

"Add password reset via email with a six-digit code, valid for 10 minutes, one active code per user."

Assume the existing system has a user service, a mail sender, and a Redis instance.

Task 1: Write a One-Page ADR​

Pick one architecturally-significant decision inside the feature. Good candidates:

  • "Where does the reset code live?" (Redis vs Postgres vs signed JWT)
  • "Is the code rate-limited per user or per IP?"
  • "Do we expire the old reset code when a new one is requested?"

Use the full ADR template:

# ADR NNNN: <short noun phrase>
Date: YYYY-MM-DD
Status: Proposed

## Context
[Forces, neutral tone, 4-8 sentences]

## Decision
We will ...

## Alternatives Considered
- <option>: <why not>
- <option>: <why not>

## Consequences
Positive: ...
Negative / risks: ...
Follow-ups: ...

Task 2: Write a Two-Page Design Doc​

Use the outline from the module's concept page. Required sections:

  • Summary
  • Goals / Non-Goals (at least two of each)
  • Background
  • Proposed Design (including data model and main endpoints)
  • Alternatives Considered (at least one)
  • Risks and Open Questions (at least three; include an abuse / security risk)
  • Rollout Plan (two paragraphs)

Task 3: Draw One Sequence Diagram​

Pick the most important scenario (likely: "user requests reset -> receives code -> submits code -> password changes"). Draw it in Mermaid. Include at least one failure path (expired code, wrong code, or rate limited).

Critique Swap​

Trade all three artifacts with a peer (or your future self, 24 hours later). For each artifact, write:

  • one thing that is genuinely well explained
  • one thing that would confuse a reader
  • one question the artifact does not answer

Common Mistake Check​

Identify the error in each:

  1. An ADR with a "Context" section that reads like a sales pitch for the chosen option.
  2. A design doc with no "Non-Goals" section.
  3. A sequence diagram showing only the happy path.
  4. A design doc and an ADR that disagree about the same decision.
  5. "Alternatives Considered: None." (in an ADR where there are obviously multiple options)

Evidence Check​

This clinic is complete when:

  • One complete ADR exists in the template.
  • One complete two-page design doc exists.
  • One Mermaid sequence diagram with at least one failure branch exists.
  • Peer (or self-delayed) critique has been written and the artifacts have been revised once.
  • You can explain, in one sentence each, what the ADR buys that the design doc does not, and vice versa.

Integrated Review Packet​

Prepare a review packet for either the meeting scheduler or restaurant-management model.

Packet contents:

  • one page of requirements and non-goals
  • one class or component diagram
  • one sequence diagram with a failure path
  • one ADR covering pattern choice, datastore boundary, or external integration
  • one critique section titled What I would simplify if requirements stopped changing
  • one test-evidence table listing behavior, test name, and risk covered

Review rule: the packet must make alternatives visible. A reviewer should be able to see not only what you chose, but what you deliberately rejected.