Clear, precise technical writing

--- name: clear-precise-technical-writing description: "Standing rules for writing and revising technical or business prose so it is specific, plain and honest about certainty. Use when drafting or editing documentation, reports, specs, release notes or explanations." --- Apply these rules whenever you write or revise explanatory prose: documentation, reports, specs, release notes, summaries and answers to technical questions. Do not apply them to fiction, slogans or text the user wants kept word for word. Before writing - Decide who the reader is and what they need to do after reading. Write for someone capable who does not share your background. - Put the point first: the conclusion, decision or answer, then the support. While writing - Name things concretely. Replace vague nouns such as 'issues', 'aspects' or 'factors' with the actual thing: the error, the date, the number, the step. - Use the simple word: 'use', not 'utilize'; 'start', not 'commence'. - Prefer active sentences that say who does what. Use the passive only when the actor is unknown or irrelevant. - Cut padding ('it is worth noting that', 'in order to') and hype ('cutting-edge', 'seamless', 'game-changing'). - Define each acronym and technical term the first time it appears. - Keep one idea per sentence and one topic per paragraph. Keep list items in the same grammatical form. - Match confidence to evidence: write 'suggests' or 'in our test' when that is what you have. Never invent figures, sources or quotes; if a number is needed and unknown, write a clearly marked placeholder. Before finishing - Reread as the reader. Remove any sentence that would not be missed. - Check that every factual claim has a basis in the material you were given. - If you edited the user's draft, list the main kinds of changes so they can review them. Avoid - Over-correcting: keep necessary technical terms and the author's voice. - Changing meaning while editing style; flag unclear passages instead of guessing what they mean.

Before: 'In order to leverage the new functionality, it is important to note that users may potentially experience some performance issues during the migration process.' After: 'During the migration on Saturday ([duration to confirm]), pages may load slowly. The new export feature is available as soon as it finishes.' Changes made: - Put the impact on the reader first. - Replaced 'performance issues' with the actual effect (slow page loads). - Cut filler ('in order to', 'it is important to note', 'may potentially'). - Named the feature instead of 'new functionality'. - Left the duration as a placeholder because the draft did not state it. Flagged for you: the draft does not say whether users need to do anything after the migration.