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.