Writing Advanced System Design Documents in English

A system design document (also called a design doc, technical spec, or RFC) is one of the most consequential written artefacts in software engineering. At the advanced level, the quality of the document depends not just on the design itself — but on how precisely you articulate trade-offs, constraints, and assumptions.

---

Document Structure

A strong design document follows a predictable structure that readers can scan quickly:

1. Context and motivation — why this design is needed now
2. Goals and non-goals — what the system will and will not do
3. High-level design — the architecture overview
4. Detailed design — component-level decisions
5. Trade-offs and alternatives considered — what you rejected and why
6. Back-of-envelope estimates — capacity and cost reasoning
7. Open questions — unresolved decisions

---

Writing the Context Section

The context section answers: Why does this matter? Use these patterns:

• “The existing approach does not scale beyond X requests per second.”
• “The current system lacks support for multi-region failover.”
• “As the team grows, manual provisioning has become a bottleneck.”
• “This design supersedes the proposal from Q3 and addresses its limitations.”

Avoid vague phrases like “we need to improve performance.” Be specific: “P99 latency exceeds 200 ms under peak load, breaching our SLA.”

---

Goals and Non-Goals

This section prevents scope creep and aligns reviewers. Use clear, parallel structure:

Goals:

• Support 10,000 concurrent connections per node.
• Provide exactly-once delivery guarantees for payment events.
• Allow zero-downtime deployments using a blue/green strategy.

Non-goals:

• This design does not address client-side caching.
• Out of scope: multi-tenancy support — that is tracked separately.
• We are not optimising for read-heavy workloads in this iteration.

---

Framing Trade-offs

The trade-off section is where senior engineers demonstrate their thinking. The key language:

Contrast connectors

• “While Option A offers lower latency, it introduces operational complexity.”
• “Option B simplifies the deployment model at the cost of vendor lock-in.”
• “Although eventual consistency reduces write latency, it complicates the client logic.”

Weighing factors

• “We prioritised operational simplicity over raw throughput.”
• “Given our team’s expertise in Postgres, we favoured a relational approach.”
• “The marginal performance gain does not justify the added complexity.”
• “This design trades storage cost for query flexibility.”

Rejecting alternatives

• “We evaluated a message-queue-based approach but rejected it because…”
• “Option C was ruled out due to its lack of official multi-region support.”
• “The consensus was that the additional operational burden outweighed the benefits.”

---

Back-of-Envelope Estimation

Back-of-envelope (BOE) calculations show that your design can handle the expected load. Write them clearly:

Template

“Assuming 50,000 daily active users, each generating 10 events per session, we estimate 500,000 events per day, or roughly 6 events per second on average. At peak (3× average), the system must handle ~18 events per second.”

Key phrases

• “Assuming a 10:1 read-to-write ratio…”
• “At a replication factor of 3, storage requirements triple.”
• “A single node can handle X RPS under our observed p95 latency target.”
• “This gives us ~Y GB/day of raw event data before compression.”
• “We budget 20% headroom above peak estimates.”

Use ~ for approximations and state your assumptions explicitly. Reviewers will challenge unsubstantiated numbers.

---

Describing Architectural Decisions

Use active, specific verbs:

Instead of	Write
”We will use Kafka"	"We route events through Kafka to decouple producers from consumers."
"The API is stateless"	"The API stores no session state, enabling horizontal scaling."
"We use caching"	"We cache responses at the edge with a 60-second TTL."
"The DB is sharded"	"We shard by user_id to distribute write load evenly.”

---

Open Questions

Close your document with unresolved decisions, not blank silence:

• “TBD: Whether to use a managed Kafka service or self-host. Depends on cost analysis (see ticket #1234).”
• “Under discussion: The retention policy for audit logs — legal review pending.”
• “Decision needed before implementation: SLA tier for the async write path.”

---

Tone and Register

Design docs are formal but not stiff. Use:

• We (not “the author” or “I”) — design is a team decision
• Present tense for the chosen design: “The service exposes a REST API.”
• Future tense for planned work: “The v2 implementation will add streaming support.”
• Avoid hedging phrases like “it might be possible that” — be direct.

---

Key Takeaways

• Context must be specific, not generic. State metrics, not feelings.
• Goals/Non-goals align reviewers and prevent scope creep.
• Trade-offs use contrast connectors: “while,” “at the cost of,” “although.”
• BOE estimates require explicit assumptions and a clear unit trail.
• Open questions are a sign of maturity, not incompleteness.
• Use active, precise verbs: route, shard, cache, expose, decouple — not “use” or “do.”

Navigating Nuance: Refining Your English for System Design

As you delve into crafting more sophisticated system design documents, you’ll quickly realize that it’s not just what you say, but how you say it. Precise language is crucial for conveying complex ideas clearly and collaboratively – especially when dealing with trade-offs and estimations. It’s easy to fall into vague terms, but senior engineers expect a level of articulation that demonstrates deep understanding and the ability to justify design choices. One common pitfall is assuming everyone shares your precise interpretation of a term; always seek confirmation. For example, when discussing “scalability,” don’t simply state “we need scalable architecture.” Instead, frame it as: “To ensure long-term scalability, we’ll prioritize horizontally scalable components using techniques like sharding and load balancing, acknowledging that this introduces operational complexity.”

Consider a scenario during code review. A reviewer might comment on your PR description with: “This section lacks clarity regarding the estimated user growth impacting database scaling. Could you elaborate on the assumptions driving these projections?” The key here isn’t to become defensive, but to rephrase your statement using more precise terminology. A better response would be: “Acknowledged – my initial estimation for user growth was based on a conservative projection of 10% annually. I’ve revised the section to explicitly state that this is an assumption and include a sensitivity analysis outlining how performance would degrade under scenarios of 20%, 30%, or even 50% growth, alongside our planned mitigation strategies.”

Another common challenge arises when presenting back-of-envelope estimations. Rather than saying “the server will handle X requests per second,” which is open to interpretation, strive for a more detailed explanation: “Based on an anticipated peak load of 10,000 requests per second and a target latency of 200ms, we’ve allocated [resource amount] to the compute tier. This calculation incorporates estimated processing time per request – approximately [time unit], factoring in network overhead and caching mechanisms.” The act of quantifying assumptions immediately demonstrates rigor and allows for more targeted discussion.

Finally, remember that phrasing directly influences the perception of your design. Using terms like “robust” or “fault-tolerant” without further context can be misleading. Instead, clearly articulate how you’re achieving resilience – “We’re implementing circuit breakers to isolate failing services and a multi-region deployment strategy for disaster recovery.” This level of detail builds confidence in your design and showcases a mature understanding of system architecture.