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.
Navigating Ambiguity: Refining Your Problem Statement with Context
Okay, so we’ve talked about structuring your problem statement – clearly defining what needs to be solved. But that’s only half the battle. The real challenge lies in ensuring everyone understands the scope, the impact, and the nuances of the issue. Let’s face it: technical problems rarely present themselves with perfectly polished phrasing. You’ll encounter ambiguity, assumptions, and potentially even differing interpretations. That’s where adding context to your problem statement becomes absolutely crucial. It’s not just about stating the symptom; it’s about painting a picture of why that symptom exists within the larger system.
Consider this scenario: Sarah is reviewing a pull request for a new feature in her team’s e-commerce platform. The PR description simply states, “Fix broken payment processing.” As a code reviewer, David immediately sees several potential issues – data validation, error handling, integration with external APIs – that aren’t explicitly addressed. He might leave a comment like, “This looks good at first glance, but the description doesn’t fully capture the scope of the problem. Are we addressing all aspects of payment processing, including potential edge cases and integration with our existing fraud detection system?” David isn’t criticizing; he’s adding crucial context that helps Sarah (and the entire team) understand the true complexity of the task.
Similarly, in a Slack conversation discussing a bug report, you might receive a message like: “Users are reporting errors when submitting orders.” A good response wouldn’t just be “Okay, fix it.” Instead, add information like, “Can we clarify which users are affected? Is this specific to mobile or desktop? And what exactly is happening during the order submission process – are we seeing timeouts, incorrect data being sent, or something else?” Providing these details helps the developer immediately narrow down the potential causes and prioritize their investigation.
The key takeaway here is that your problem statement isn’t a static declaration; it’s an evolving description of the challenge. By proactively adding context—asking clarifying questions, referencing related systems, outlining anticipated impacts – you’re setting the stage for more effective collaboration and ultimately, a better solution. Don’t be afraid to probe deeper and ensure everyone is on the same page before diving into the technical details. Remember, a well-defined problem statement acts as the foundation for a successful design.