5 exercises — cutting wordiness, parallel structure in lists, relative clauses, ambiguous pronouns, and clear ticket writing. Every sentence should earn its place.
4 rules for clear technical writing
Cut the filler — "in the event that" → "if" · "is able to" → "can"
Use parallel structure — match all list items to the same grammatical form
Name it, don't pronoun it — if "it" could mean two things, use the noun
Specific over vague — "iOS Safari 17" not "some devices", "Monday" not "soon"
0 / 5 completed
1 / 5
Which rewrite of this sentence is the most concise and clear for technical documentation?
Original: "In the event that the user is not able to successfully authenticate themselves with the system, an error message will be shown to them on the screen."
"If the user cannot authenticate, the system will display an error message." — 12 words vs. 30. Key techniques: (1) Replace wordy hedges: in the event that → if. (2) Use active rather than passive voice for clarity: the system will display vs. will be shown to them. (3) Remove redundant pronouns: authenticate themselves → authenticate. (4) Cut location padding: on the screen is implied for a UI message. Technical documentation should answer "what" and "when" — no filler words.
2 / 5
A developer writes this list in the README. Which version uses parallel structure correctly?
"The API supports: creating new users, reading existing records, and deleting entries." — All three list items use the -ing (gerund) form, making them grammatically parallel. Parallel structure means each item in a list uses the same grammatical form. Mixing verb forms (creating / to read / deletion) is jarring and error-prone. In IT docs this matters especially for: feature lists, CLI options, API capabilities, setup steps. If your list starts with a verb (imperative), keep all items imperative: Run the server · Configure the env · Test the endpoint.
3 / 5
Combine these two sentences into one using a relative clause:
"The function validates the input. The input must be a non-empty string."
"The function validates the input, which must be a non-empty string." — Use a non-restrictive relative clause (with comma + which) when the clause adds information about something already identified. Contrast: the input that fails validation (restrictive — narrows down which input). In technical writing: use that for restrictive clauses (the endpoint that handles auth) and which for non-restrictive commentary (the endpoint, which was introduced in v2, handles auth). Avoid stacking relative clauses — if a sentence needs two whichs, split it into two sentences.
4 / 5
This sentence from a PR description is ambiguous: "After the middleware processes the request, it logs it." — What is the clearest rewrite?
"After the middleware processes the request, the middleware logs the request." — The original is ambiguous because "it" and "it" could refer to either middleware or request. The fix: replace pronouns with explicit nouns when the referent isn't 100% clear. In technical writing and code comments especially, ambiguous pronouns cause bugs ("update the cache after the DB — it takes 100ms" — what is slow?). Dangling modifier check: always ask "who/what does the pronoun refer to?" If there's any doubt, name it explicitly.
5 / 5
Which of these ticket descriptions is clearest and most actionable?
"Login button unresponsive on iOS Safari 17 — tapping the button does nothing; expected: form submits and redirects to /dashboard." — This follows ticket-writing best practices: (1) Component + symptom in title: "Login button unresponsive". (2) Specific environment: "iOS Safari 17" — not "some devices". (3) Actual vs. expected: exactly what happens vs. what should happen. (4) No hedging: "maybe", "soon", "some users" are vague and unjustified. Good tickets save hours of back-and-forth clarification. The same principles apply to bug reports, error messages, and commit message bodies.