How to Write a Design Doc Problem Statement in English
Learn the English structure and phrasing for writing a clear, specific problem statement at the start of a technical design document.
A design doc that opens with a vague problem statement — “our system needs to be more scalable” — invites vague solutions and vague debate. A precise problem statement, with concrete symptoms and named constraints, focuses the entire document that follows. This guide covers the English structure for writing one that reviewers can actually evaluate.
Key Vocabulary
Problem statement — the opening section of a design doc that names the specific issue being solved, distinct from the proposed solution, which comes later. “The problem statement should describe what’s broken today, not what we’re planning to build — save the solution for the next section.”
Symptom — an observable, specific effect of the underlying problem, stated in concrete terms (a number, an error, a user complaint) rather than a general impression. “Instead of writing ‘the system is slow,’ state the symptom precisely: ‘p99 latency on the checkout endpoint exceeds four seconds during peak traffic.’”
Root cause (hypothesized) — the underlying reason the symptom occurs, clearly marked as a hypothesis if it hasn’t been fully confirmed, to avoid overstating certainty. “We believe the root cause is a lack of connection pooling, though we haven’t fully confirmed it — that’s part of what this doc proposes to investigate.”
Constraint — a boundary condition the solution must respect, such as a deadline, a budget, a backward-compatibility requirement, or a team’s available expertise. “One constraint worth stating up front: we can’t require a database migration, since the team doesn’t have a maintenance window scheduled for another quarter.”
Non-goal — something the document explicitly won’t address, stated to prevent scope creep and unnecessary debate during review. “We’re calling out ‘supporting offline mode’ as a non-goal for this doc — it’s a real need, but it belongs in a separate design.”
Success criteria — a measurable definition of what “solved” looks like, stated early so the rest of the document can be evaluated against it. “Success criteria: p99 latency under 500ms and zero increase in error rate, measured over a two-week window post-launch.”
Common Phrases
- “Here’s the specific symptom we’re seeing, measured over the last 30 days.”
- “We believe the root cause is X, though this hasn’t been fully confirmed.”
- “One constraint we’re operating under is…”
- “Explicitly out of scope for this doc: …”
- “We’ll consider this solved when [specific, measurable outcome].”
Example Sentences
Opening a design doc with a concrete problem statement: “Over the last month, the notification service has dropped an average of 3% of messages during peak load, and support tickets citing missed notifications have tripled. We believe this is caused by the queue’s fixed worker pool size, which doesn’t scale with incoming volume.”
Stating a constraint clearly: “Any proposed solution needs to be deployable without downtime, since this service handles time-sensitive alerts and can’t have a maintenance window.”
Defining a non-goal to prevent scope creep: “This document proposes a fix for message delivery reliability specifically. Improving notification content or adding new notification types is a separate, later initiative and is out of scope here.”
Professional Tips
- Lead with a specific symptom, ideally with a number, before any explanation — reviewers can evaluate “3% message loss” far more easily than “reliability issues.”
- Mark a hypothesized root cause explicitly as a hypothesis if it isn’t fully confirmed — presenting a guess as settled fact undermines trust when it turns out to be wrong.
- State constraints before proposing a solution — a solution that violates an unstated constraint wastes review cycles when someone points it out late.
- Always include a non-goals section — it’s one of the fastest ways to prevent a design review from sprawling into unrelated debates.
Practice Exercise
- Write a two-sentence problem statement for a hypothetical performance issue, including a specific symptom.
- Write one constraint statement that would shape what solutions are viable.
- Write a non-goals sentence that would keep a design review focused.