Writing Technical Design Documents in English: Structure and Language
Learn to write clear technical design documents in English: structure, the goals/non-goals pattern, proposing solutions, weighing trade-offs, and the right tense and voice.
A technical design document (often “design doc,” “RFC,” or “tech spec”) is how engineers propose significant work before writing code. It’s also one of the highest-leverage pieces of writing in your career: a good one gets your design approved quickly; a confusing one stalls in review for weeks. For non-native English speakers, the challenge isn’t just grammar — it’s structure, tone, and knowing which tense to use where. This guide covers all three.
The standard structure
Most design docs follow a recognisable skeleton. You don’t need every section, but reviewers expect this order:
- Title and metadata — author, date, status, reviewers.
- Summary / TL;DR — the whole doc in three sentences.
- Background / Context — why this is needed.
- Goals and Non-goals — what’s in and out of scope.
- Proposed solution — the design itself.
- Alternatives considered — what you rejected and why.
- Trade-offs and risks — the honest downsides.
- Rollout plan — how it ships.
- Open questions — what’s still undecided.
The rest of this guide is about writing each part well.
The summary: write it last, put it first
Reviewers decide in 30 seconds whether to read carefully. Give them the gist immediately.
Before (buries the point): “This document discusses various considerations regarding the current state of our caching infrastructure and explores potential approaches.”
After (states it): “This doc proposes replacing our three ad-hoc caches with a single Redis layer. Goal: cut cache-related incidents and onboarding time. Recommendation: migrate over two sprints behind a feature flag.”
Useful openers: “This doc proposes…,” “In short, we will…,” “TL;DR:…”
Goals and Non-goals: the most underused pattern
The Goals / Non-goals section prevents scope creep and review tangents. Goals say what success looks like; non-goals explicitly say what you’re not doing — so reviewers don’t waste time arguing about it.
Goals
- Reduce cache-related incidents by consolidating to one system.
- Cut new-engineer onboarding from days to hours.
Non-goals
- Replacing the primary database. (Out of scope.)
- Optimising for multi-region. (Future work.)
Phrasing for non-goals: “This is explicitly out of scope,” “We are not addressing X in this doc,” “Deferred to a follow-up.”
Listing non-goals signals senior judgement — you’ve thought about the boundaries.
Tense and voice: the rules
This is where non-native writers most often slip. The tenses map cleanly to sections:
- Background: present and past (“We currently run three caches; this grew organically.”)
- Proposed solution: future/modal (“We will introduce a Redis layer. Services will read through it.”)
- Trade-offs: present (“This introduces a new dependency.”)
- Rollout: future (“We will roll out behind a flag, starting with the read path.”)
Voice: Prefer active voice for decisions and ownership (“We will migrate…”). Use passive only when the actor is irrelevant (“Requests are routed through the gateway”). Overusing passive makes a doc sound evasive — a common problem in translated technical writing.
Proposing the solution: be concrete and confident
The proposed-solution section is no place for hedging. Describe the design as a plan, not a possibility.
- “The system consists of three components: …”
- “A request flows from the client, through the gateway, into the cache layer.”
- “We introduce a read-through cache keyed by user ID.”
- “On a cache miss, the service falls back to the database.”
Use diagrams and label them in prose: “As shown in Figure 1, …” Walk the reader through the happy path first, then the edge cases and failure modes.
Vocabulary for design description: component, data flow, happy path, edge case, failure mode, fallback, invariant, boundary.
Alternatives considered: show your work
A design doc with no alternatives reads as naive — like you picked the first idea. Showing rejected options proves rigour.
Alternative 1: Keep the status quo. Rejected — fragmentation persists. Alternative 2: Memcached instead of Redis. Rejected — we need persistence and richer data types. Alternative 3: Build in-house. Rejected — not worth the maintenance cost.
Phrasing: “We considered X but rejected it because…,” “The deciding factor was…,” “X was tempting, but…”
Trade-offs and risks: honesty earns trust
Name the downsides yourself, before reviewers do. The strongest phrase here is “we accept the risk that…”:
“Trade-off: introducing Redis adds an operational dependency and a new failure mode. We accept this because the reduction in cache-related incidents outweighs it. Risk: a Redis outage degrades read latency; mitigation: the service falls back to the database.”
Pair every risk with a mitigation. A risk with no mitigation looks like an oversight.
Open questions: it’s okay not to know everything
A short Open questions section invites the discussion you actually want:
- Should we cache writes too, or read-only for now?
- What’s the right TTL for session data? (Need input from the auth team.)
Phrasing: “Open question:,” “We’re undecided on…,” “Input welcome on…,” “I’d like reviewers’ thoughts on…”
Tone: confident but not arrogant
Aim for measured confidence. You’re proposing, not commanding:
- “I propose we…” (good)
- “We should consider…” (slightly weaker, fine for options)
- “We must do X or everything fails.” (too dramatic unless true)
- “Obviously, the only sane choice is…” (arrogant — avoid)
When inviting review: “Feedback welcome,” “Please poke holes in this,” “Open to alternatives on the rollout.”
Common mistakes non-native writers make
- No TL;DR. Reviewers shouldn’t hunt for the point. Lead with it.
- Overusing passive voice. “It was decided” hides who decided. Say “we decided.”
- Skipping non-goals. Without them, reviews wander into scope you never intended.
- No alternatives. Looks like you didn’t think. Always show 2–3.
- Wrong tense in the proposal. Use will for the plan, present for current state — don’t mix them.
Key takeaways
- Follow the standard skeleton; reviewers expect Summary → Context → Goals/Non-goals → Solution → Alternatives → Trade-offs → Rollout → Open questions.
- Write the TL;DR last, put it first — reviewers decide in 30 seconds.
- Use Non-goals to fence off scope; it signals senior judgement.
- Match tense to section: present for context, will for the plan, present for trade-offs.
- Prefer active voice, name alternatives, and pair every risk with a mitigation. Honesty about downsides is what gets a doc approved.