Writing Implementation Notes & Caveats
Note vs Warning, specific caveats, dependency documentation, "as of this writing", and migration notes
Implementation notes essentials
- Note vs Warning: Note = non-obvious but important; Warning = miss this and something breaks
- Caveats: assumption + specific threshold + consequence if exceeded + action/mitigation
- Dependencies: service + owner + failure mode + fallback + SLA + escalation path
- "As of this writing": include date + condition that makes it true now + when/what to check
- Migration notes: from → to + how + when + idempotent? + rollback plan + owner
Question 0 of 5
When should a "Note:" or "Warning:" be used in a Design Doc's implementation section?
Note = non-obvious but important; Warning = miss this and something breaks. Usage guide:
- Note: "Note: This service assumes the upstream payment-service uses UTC timestamps. If another timezone is used, date-range queries will return incorrect results." — not obvious, but won't cause an incident unless the assumption is violated
- Warning: "Warning: Do not run the migration script more than once — it is not idempotent. Running it twice will delete all user preferences." — missing this causes data loss
- ❌ Using "Note:" before every paragraph — everything becomes equally highlighted, which means nothing is highlighted
- ❌ Using "Warning:" for non-critical information — engineers start ignoring warnings if they're overused
Which caveat is written most effectively in implementation notes?
Caveat formula: what the assumption is + the specific threshold + what breaks if exceeded + what to do about it. Caveat writing breakdown:
- Assumption: "event queue depth stays below 10,000 messages" — specific, measurable
- Threshold: "above 10,000 messages" — not "under high load" or "in some cases"
- Consequence: "consumer lag will exceed our 5-second SLA" — concrete, testable failure mode
- Mitigation/action: "load testing above 8,000 messages/second is recommended before launch" — tells the implementer what to do
A Design Doc implementation section contains: "This design depends on the auth-service being available." How should this dependency be documented more completely?
Dependency documentation: service + owner + failure mode + fallback (or lack of) + SLA + escalation path. Complete dependency entry:
- What: "auth-service" — the dependency
- Owner: "@platform-team" — who to contact
- Failure mode: "all write operations will return 503" — what the impact on this design is when the dependency fails
- Fallback: explicit statement of "no fallback planned" — important because absence of a fallback is itself a design decision
- Justification: "acceptable given 99.95% SLA" — the reasoning behind accepting the risk
- Escalation: "PagerDuty 'auth-service' rotation" — where to go when it breaks at 3am
Which sentence correctly uses the phrase "as of this writing" in implementation notes?
"As of this writing" is for current-state claims that are expected to change — always include a date, the condition that makes it true now, and what to check or when to revisit. "As of this writing" use cases:
- ✅ Current limitations of a dependency that are expected to be resolved: "As of this writing (May 2026), auth-service does not support refresh tokens"
- ✅ Current team or resource constraints: "As of this writing, we have no Kafka operational expertise in-house"
- ✅ Current state of an external spec or standard: "As of this writing, the OAuth2 extension for X is in draft"
- Date: "(May 2026)" — makes it interpretable after time passes
- Tracking item or condition: "tracked in PAYMENT-4421", "when payment-service adds native idempotency" — tells future readers when to remove the workaround
A migration note in a Design Doc reads: "Existing users will need to migrate their data." What is missing?
Migration note formula: from → to + how + when + idempotent? + rollback + owner. Migration note components:
- From → to: "session tokens (format v1) → v2 format" — specific data and transformation
- How: "migration script (scripts/migrate-tokens.sh) runs automatically as part of deployment" — no ambiguity about who runs what
- When: "before the new auth-service is deployed" — critical for pipeline ordering
- Idempotency: "idempotent — safe to re-run on failure" — essential for automated migrations; if not idempotent, must say so with explicit warning
- Rollback: "old auth-service reads both formats for 30 days" — the safety net
- Owner: "@backend-team" — who to call when it breaks at 3am