Writing Design Documents

Option B demonstrates the professional design document problem statement. It has five essential properties:

① Historical context — "built in 2021 for 8,000 accounts, now serving 94,000" — this explains why the system is strained without blaming the original authors. It transforms a systems failure into a scaling story, which is honest and accurate. Readers trust a problem statement that explains why the problem exists.

② Quantified symptoms — "50,000 emails/day, 12% bounce rate, industry average 2%" — the comparison to industry average is a critical move. Without it, 12% is ambiguous. With it, 12% is clearly a 6x deviation from acceptable.

③ Impact in business terms — "~6,000 notifications per day lost, including password resets, purchase confirmations, and security alerts" — this maps a technical metric (bounce rate) to user impact. Security alerts being silently dropped is a fundamentally different statement than "some emails are lost".

④ Second problem stated clearly — the opted-out users with no fallback channel — this is a scoping clarity move; it establishes that the problem has two dimensions, both of which the design must address.

⑤ Explicit scope boundary — "delivery layer only — templating and composition out of scope" — this is the sentence that prevents scope creep. Every good design doc problem section should define what is and is not in scope.

Option A is too vague ("needs improvement") and contains a solution ("better system") inside the problem statement — solution bias in the problem section closes off design alternatives prematurely.

Option B demonstrates the gold standard for "Alternatives Considered" sections.

The purpose of this section is to prove that the chosen option was selected, not assumed. It must answer: "Why didn't you just do [X]?" before the reader asks. If you can't clearly articulate why alternatives were rejected, your design may not be fully considered.

Why the table format works here:
• Forces comparable evaluation of each option — pros and cons must be stated for all options, not just the ones that support your conclusion
• Makes the rejection rationale explicit — "GDPR data residency constraints for EU users" is a specific, true reason that the reader can verify
• The verdict column names whether each option was rejected or selected, and why in one sentence

Properties of a good alternatives section:
① Specific rejection reasons — "doesn't address the single-provider architecture" and "6-month ceiling" are specific. "Various drawbacks" (Option D) is evasion.
② Real costs — "$38K/year at current volume" — put the actual number in the document. This grounds the "cost" objection in reality.
③ Fair treatment of alternatives — Option 1's pros are real (low effort, familiar codebase). The alternatives section should be a fair assessment, not a straw man exercise where alternatives are weakened to make the recommendation look better. Reviewers notice and correct for this.
④ Honest about downsides of the chosen option — "Higher upfront effort (~6 sprints)" — if your recommended option has no cons, the reader will supply them mentally and distrust the whole section.

Option A contains solution bias ("it's the best approach") without specific analysis. Option C is adequate but lacks costs. Option D is a content-free placeholder.

Option B is the implementation notes standard. Implementation notes are fundamentally different from the rest of a design document — they are directives, not proposals.

Four properties of good implementation notes:

① Named DRI (Directly Responsible Individual) — if no name is attached to an implementation decision, no one is accountable for it during the build. DRIs prevent "I thought you were handling that" scenarios.

② Imperative voice for decisions — "Use SQS with a DLQ", "Do not implement a custom retry loop" — the design doc decided this; the implementation notes are directions, not suggestions. The "don't" statements are often more important than the "do" statements because they prevent reinvention of solved problems.

③ Specific enough to prevent misimplementation — "exponential with jitter — base 30s, max 2 hours" — not "use exponential backoff". The specific parameters prevent three different implementations from three different interpretations. The AWS docs reference points to an external source so the implementer doesn't have to figure out the formula.

④ Explicit about what's NOT in scope for this component — "message deduplication across channels — see §5.3" — this prevents the implementer from trying to solve a problem that's already being solved elsewhere, which would create a conflict.

Option C uses "consider" — design doc implementation notes should use definitive verbs, not suggestions. Option A ("team will decide specifics") is a placeholder that shouldn't be in a design doc if the design isn't actually decided. Option D contains no implementation content.