English for developers: technical writing
Writing a Design Doc in English: Structure, Phrases, and How to Sound Confident
October 21, 2026
The structure every design doc needs, plus the exact phrases for goals, non-goals, alternatives considered, open questions, and asking for sign-off.
The structure of a design doc
Most teams expect roughly the same shape: a problem statement, goals and non-goals, the proposed solution, alternatives considered, open questions, and a rollout plan. Getting the structure right matters, but it is the specific English phrasing inside each section that decides whether reviewers engage with the substance of your proposal or get stuck arguing about wording.
The biggest trap is the register: hedge too much and your proposal reads as unconfident noise; sound too certain and you shut down the review you actually need. This guide gives you the exact phrases for each section, and the calibration between the two extremes.
Key Takeaways
- A goal needs a number. 'Make it fast' is not testable; 'p99 latency under 200ms' is.
- Write non-goals explicitly. An unwritten non-goal becomes a derailing argument in the comments later.
- For every alternative, give the tradeoff and the specific reason you rejected it, not just the option you picked.
- An open question needs a lean and a named owner. 'Not sure about this' with no direction reads as unprepared.
- Ask for sign-off with a deadline and a default outcome, so the doc does not sit in review limbo.
The sections, in order
- 1
Problem statement
What is broken or missing today, in one or two paragraphs. No solution yet.
- 2
Goals
Testable outcomes the design must achieve.
- 3
Non-goals
What is explicitly out of scope for this document.
- 4
Proposed solution
The design itself, with diagrams if useful.
- 5
Alternatives considered
What else you evaluated, and why you did not choose it.
- 6
Open questions
What is still unresolved, directed at a specific team or person when possible.
- 7
Rollout plan
How this ships: phases, feature flags, rollback plan.
1. Writing clear goals and non-goals
A goal without a number is not a goal. A non-goal that is never written down becomes an argument in the comments three weeks from now.
“The goal of this document is to propose a solution for the checkout timeout issue.”
Open the doc by stating the goal directly. Do not bury it under three paragraphs of background.
“This system must support 10,000 writes per second with p99 latency under 200ms.”
A goal should be testable. 'Make it fast' is not a goal. A number is.
“This document does not address the migration of existing data. That will be covered in a separate RFC.”
An explicit non-goal prevents reviewers from derailing the discussion into unrelated territory.
“We are explicitly not solving the multi-region case in this iteration.”
Stops scope creep in the comments before it starts.
2. Describing alternatives considered
The template is always the same: what you considered, the tradeoff, and the specific reason you rejected it. Never present only the option you chose.
“We considered caching at the application layer, but rejected it because it would not survive a service restart.”
The template for every alternative: what you considered, and the specific reason you rejected it.
“Option A is faster to ship but harder to maintain long-term. Option B is the opposite. We are choosing B because maintainability is our priority this quarter.”
Present both options evenhandedly before stating your choice. This reads as a decision, not a defense.
“This approach trades some write latency for much simpler failure recovery.”
Naming the tradeoff in one sentence is clearer than a long paragraph justifying it.
“An earlier draft proposed a synchronous call here. We moved away from it after load testing showed it did not hold up past 500 requests per second.”
Showing you considered and tested an alternative builds more credibility than only presenting the final answer.
3. Flagging open questions
An open question with a lean and a named owner gets answered. A vague 'not sure about this part' does not.
“Open question: should this happen synchronously or asynchronously? Leaning toward async, open to pushback in review.”
Give a direction even when you are unsure. A lean plus an invitation for feedback reads as confident, not unprepared.
“We have not yet decided on the retry strategy. Flagging this for discussion in the review.”
Naming an unresolved decision explicitly is better than hoping nobody notices it is missing.
“This is still an open question. Feedback from the security team would be especially useful here.”
Pointing the open question at a specific team or person gets it answered faster than a generic 'feedback welcome'.
4. Asking for sign-off
Name who needs to approve, by when, and what happens by default if nobody objects.
“Please review by Friday. Flag any blocking concerns in the comments.”
Asking for review with a clear deadline gets responses. An open-ended 'thoughts welcome' often does not.
“I am looking for sign-off from the platform and security teams before starting implementation.”
Naming exactly who needs to approve avoids the doc sitting in limbo with no one sure if they are the blocker.
“If there are no blocking objections by Monday, I will consider this approved and start implementation.”
A default outcome and a date move the doc out of endless review and into a decision.
Calibrating your register: not too hedged, not too certain
Too far one way
“I think maybe we could possibly try using a queue here, if that makes sense?”
Calibrated
“I propose using a queue here to decouple the two services. Open to alternatives if the latency numbers do not hold up.”
Too much hedging reads as a lack of confidence in your own proposal, even when the underlying idea is solid.
Too far one way
“This is definitely the only way to solve this. There is no other option.”
Calibrated
“Based on the load testing results, I believe this is the best approach. I am open to reconsidering if new constraints come up.”
Sounding falsely certain shuts down the review you actually need. State your conclusion, then leave the door open.
Related articles
Ready to practice your English at work?
Lingua-e has interactive exercises built around real developer conversations: standups, code reviews, retrospectives, and more. Practice until it comes naturally.
Try Lingua-e for free
Written by
Roxana LafuenteLingua-e's founder
Roxana Lafuente is a software engineer with 8+ years of experience. At the beginning of her career, even though she had already passed the First Certificate in English, she still froze every time she had to speak up in the daily standup. That was a gap nobody was fixing. After 2,000+ standups, she figured out what actually builds fluency: practice that looks like your real work. She built Lingua-e so other developers wouldn't have to take the long road to feel confident working in an international development environment.