5 exercises — identifying and fixing ambiguous pronouns (it, this, they, that) in documentation, incident reports, and code comments.
0 / 5 completed
1 / 5
A PR description reads: "The service calls the database and then it returns a response. It logs the result." What is the problem with this sentence?
Option B is correct. When a sentence contains multiple possible referents (the service, the database), the pronoun "it" creates ambiguity. Readers must guess — and in technical writing, guessing is a defect. Fix: restate the noun. "The service calls the database and then returns a response. The service also logs the result." In technical documents, every pronoun must have one unambiguous antecedent within the same sentence or the immediately preceding sentence. When in doubt, repeat the noun.
2 / 5
An incident report states: "The load balancer forwards requests to the backend. This caused the outage." What does "This" refer to?
Option C is correct. "This" used as a standalone subject — sometimes called a "naked this" — is one of the most common errors in incident writing. It nominally refers to "the previous statement as a whole", but in technical writing the reader needs precision. Fix: "This misconfiguration caused the outage." or "This forwarding behaviour caused the outage." Always complete "this" with a descriptive noun: "this issue", "this pattern", "this delay", "this condition". The noun you choose also demonstrates your understanding of the root cause.
3 / 5
An architecture doc says: "The API gateway and the auth service communicate over mTLS. They handle all external requests." Which rewrite improves pronoun clarity?
Option C is the clearest. When "they" could refer to either one of two named components, or to both together, the correct fix is to restate each noun with its specific responsibility. This forces the writer to clarify the architecture and makes the document unambiguous. Option A replaces "they" with "it", which is still ambiguous. Option B compresses information but loses the distinction between the two components. Option D introduces a new pronoun ("them") without improving clarity. Technical writing rule: when a plural pronoun follows two distinct nouns with different roles, expand — do not compress.
4 / 5
A code comment says: "// The validator calls the parser, which validates the input. If it fails, retry." Which "it" is ambiguous here?
Option B is correct. "If it fails" is ambiguous because there are multiple candidates: the validator (calling fails), the parser (parsing fails), or the validation step (validation result fails). The rule "it refers to the most recently mentioned noun" is a guideline, not a guarantee, and in technical contexts it fails whenever the closest noun is not the actual referent. Fix: "// If validation fails, retry." or "// If the parser call fails, retry." In code comments, precision matters as much as in documentation — ambiguous retry conditions can cause unexpected loops or silent failures.
5 / 5
A README says: "Install the CLI and configure the environment. Once you do this, the build will succeed." How should "this" be improved?
Option C is the clearest because it explicitly restates both actions — install and configure — removing all ambiguity. "This", "it", and "that" used to refer to a sequence of actions are all weak in technical writing. Option A replaces "this" with "it", which is equally vague. Option B ("that") is marginally more formal but still vague. Option D ("once done") is concise but loses specificity. In READMEs and setup guides, step references should be explicit: readers may skip steps, read out of order, or be unclear which steps count as "done". Explicit summary sentences also serve as natural checklists.