How to Give Feedback on a Technical Design Doc in English

Reviewing a colleague’s design document is one of the highest-leverage moments in software development — catching a flawed assumption on paper is far cheaper than catching it in production. But giving that feedback well, in English, requires more than technical knowledge: it requires phrasing that raises real concerns clearly without discouraging the author or derailing the discussion into nitpicking. This post covers the vocabulary and phrasing patterns that make design doc feedback both honest and constructive.

Key Vocabulary

Open question — an unresolved issue in the document that the author has flagged (or should flag) as needing further discussion before the design is finalized. “Section 4 lists this as an open question — I think we need to resolve it before approving the doc.”

Blocking concern — a piece of feedback significant enough that the design should not move forward until it’s addressed, as opposed to a suggestion the author can take or leave. “This is a blocking concern for me: the doc doesn’t address what happens if the downstream service is unavailable during the migration.”

Non-blocking comment — feedback that the reviewer considers worth raising but does not require resolution before approval, often a suggestion or minor concern. “Non-blocking comment: have you considered naming this field expiresAt instead of expiry for consistency with the rest of the schema?”

Approve with conditions — a review outcome where the reviewer agrees with the overall design but requires specific changes or clarifications before final sign-off. “I’ll approve with conditions — please add a section on rollback before this goes to implementation.”

Alternative considered — a section of a design doc, or a piece of feedback, describing another approach that was evaluated and rejected, along with the reasoning. “Can you add an alternative considered section explaining why you ruled out using the existing queue instead of introducing a new one?”

Scope boundary — the explicit line between what a design addresses and what it deliberately leaves out, used to keep review feedback focused. “That’s a good point, but it’s outside the scope boundary of this doc — let’s track it as a follow-up.”

Sign-off — the formal approval from a reviewer or stakeholder indicating the design is ready to move into implementation. “We have sign-off from the infrastructure team; we’re still waiting on security before we can start building.”

Common Phrases

• “This is a blocking concern — I don’t think we can proceed without addressing it.”
• “Non-blocking, but worth considering: have you thought about the failure mode here?”
• “Could you expand on why this approach was chosen over the alternative you mentioned in standup?”
• “I’d like to see this scoped down before implementation starts — can we split this into two phases?”
• “I’m approving with one condition: please add the rollback plan before merging.”
• “This falls outside the scope boundary of the doc — let’s not try to solve it here.”

Example Sentences

Raising a blocking concern: “I have a blocking concern about the retry logic described in section 3. As written, a failed write could be retried indefinitely without a circuit breaker, which risks amplifying an outage rather than recovering from it. Could we add an explicit retry limit and a fallback behavior before this moves forward?”

Leaving a non-blocking suggestion: “Non-blocking comment: the doc doesn’t mention monitoring or alerting for the new pipeline. It’s not required for approval, but I’d strongly recommend adding a short section before implementation starts, so we’re not retrofitting observability after an incident.”

Approving with conditions: “Overall this is a solid design and addresses the core scaling problem well. I’m approving with two conditions: first, add the alternative considered section we discussed regarding the existing queue; second, clarify the rollback plan in case the migration needs to be reversed mid-flight.”

Professional Tips

• Always label feedback as blocking or non-blocking explicitly — leaving this ambiguous is the single most common cause of confused, drawn-out design review threads.
• Ask “could you expand on why” rather than “this is wrong” when you disagree with a decision — it invites explanation and often surfaces context you were missing.
• Use “approve with conditions” rather than a flat rejection when the core design is sound but specific gaps remain — it moves the conversation forward instead of restarting it.
• When a topic is out of scope, say so explicitly and suggest tracking it separately, rather than letting the discussion drift — this keeps the review focused and respects the author’s time.

Practice Exercise

1. Write a blocking-concern comment on a design doc that doesn’t address what happens when an external API is unavailable.
2. Write a two-sentence approval-with-conditions comment for a design that is solid but missing a monitoring section.
3. Explain, in two sentences, the difference between a blocking concern and a non-blocking comment to a junior engineer writing their first design doc review.

Navigating Nuance: Specific Language for Non-Native Speakers

Giving feedback on a technical design document is more than just stating your opinion; it’s about clearly articulating why you have that opinion and proposing solutions. For non-native English speakers, this can feel particularly challenging due to the subtleties of professional phrasing and vocabulary. Let’s focus on building confidence in expressing yourself effectively, especially when dealing with potentially complex technical concepts. A key shift is moving beyond simply saying “this is bad” to explaining what makes it problematic and what needs improvement. This demonstrates respect for the designer’s work while simultaneously offering constructive input.

One common hurdle is using overly direct language. Phrases like “This is wrong” can come across as confrontational, even if that’s not your intention. Instead, consider phrasing such as, “I have some concerns regarding the scalability of this approach given the projected user growth outlined in the requirements document.” This softens the criticism by framing it within the context of the overall design goals. Similarly, when seeking clarification, avoid asking “What does this mean?” which can sound simplistic. A more sophisticated approach is: “Could you elaborate on the rationale behind using [specific technology/approach]? I’d like to better understand how it aligns with the documented performance requirements.” Practice articulating your thoughts step-by-step – start with acknowledging a positive aspect before introducing any reservations.

Furthermore, pay close attention to conditional language. Often, feedback isn’t about outright rejection but rather proposing modifications or suggesting alternative solutions with conditions. For example, instead of saying “Don’t use this database,” you could say: “While I appreciate the consideration of using [Database A], I’m concerned about its limitations regarding transaction volume. Perhaps we could explore [Database B] as an alternative, assuming we can successfully migrate our existing data within the stipulated timeframe.” Using phrases like “assuming,” “provided that,” or “subject to” allows you to frame your feedback as a suggestion rather than a firm directive. Learning to use these conditional statements accurately is vital for demonstrating professionalism and collaborative thinking. Don’t be afraid to ask a colleague to review your phrasing – a fresh pair of eyes can often spot areas where the language could be more precise or nuanced.

Finally, remember that written communication in technical contexts relies heavily on precision. Avoiding ambiguous terms and using specific vocabulary related to the design domain is crucial. Instead of saying “it’s slow,” you might say “the latency between the API call and data retrieval exceeds the acceptable threshold defined in section 3.2.” Building a glossary of common technical terms – both your own and those used by your team – can be incredibly helpful when formulating feedback, ensuring you’re communicating with accuracy and confidence.