How to Give Feedback on Documentation in English

Reviewing documentation calls for a different kind of feedback than reviewing code — the “bug” you’re flagging might be a confusing sentence rather than a broken function, and it’s easy to either be too vague (“this is unclear”) or too harsh (“this doesn’t make sense”). This guide covers the English for giving documentation feedback that’s specific and easy to act on.

Key Vocabulary

Gap — missing information a reader would need but the document doesn’t provide, distinct from something that’s present but poorly explained. “There’s a gap here — the doc explains how to configure the client, but never mentions what happens if the config file is missing.”

Ambiguity — a passage that could reasonably be read more than one way, which is especially risky in instructions meant to be followed step by step. “This step is ambiguous — ‘restart the service’ could mean the whole VM or just the process, and those are very different actions.”

Staleness — a section that was accurate when written but no longer reflects the current system, often the result of code changing without a corresponding doc update. “This section shows the old CLI flags — it’s gone stale since the tool was rewritten last quarter.”

Reader assumption — a piece of prior knowledge the document assumes the reader has, which may not hold for the actual audience (new hires, external users, etc.). “This section assumes the reader already knows what a webhook is — that’s probably fine for internal docs, but not for the public API reference.”

Actionable suggestion — a specific proposed fix accompanying the feedback, rather than just pointing out a problem and leaving the writer to guess at a solution. “Instead of just flagging that this paragraph is confusing, I suggested splitting it into three numbered steps with a code example after each one.”

Common Phrases

• “There’s a gap here — it doesn’t cover what happens when [specific edge case].”
• “This is ambiguous — could you clarify whether it means X or Y?”
• “This section looks like it’s gone stale since [recent change] — worth double-checking.”
• “This assumes the reader already knows [concept] — should we add a link or a short explanation?”
• “One suggestion: could we add a code example here to make this concrete?”

Example Sentences

Flagging a gap constructively: “Great step-by-step structure overall. One gap I noticed: the doc walks through the happy path but doesn’t mention what error message appears if the API key is invalid — that’s probably the first thing a new user will hit.”

Pointing out ambiguity with a suggested fix: “This sentence is a bit ambiguous: ‘update the config and redeploy’ — does redeploy mean the whole cluster or just this service? Might be worth naming the exact command to remove any doubt.”

Flagging staleness diplomatically: “I think this section might have gone stale — the screenshots still show the old dashboard layout. Should we regenerate them, or is a rewrite of this section overdue anyway?”

Professional Tips

• Distinguish a gap (missing entirely) from an ambiguity (present but unclear) in your feedback — they need different kinds of edits, and conflating them slows the writer down.
• Flag staleness without assuming carelessness — documentation goes stale naturally as code evolves, and framing it as “worth double-checking” rather than “this is wrong” keeps the tone collaborative.
• Name the reader assumption explicitly when a section might be too advanced or too basic for its actual audience — it’s a common and easy-to-fix issue once pointed out.
• Always try to include an actionable suggestion, even a rough one — “this is confusing” leaves a writer guessing, but “maybe split this into numbered steps” gives them somewhere concrete to start.

Practice Exercise

1. Write a two-sentence comment flagging a gap in a hypothetical setup guide.
2. Write one sentence pointing out an ambiguous instruction and proposing a clarification.
3. Write a sentence flagging a stale section diplomatically, without implying blame.