Writing practice / How-to
Edit for clarity and consistency
Replace vague wording with specific actors, actions, and terms.
Make the action explicit
Prefer a named actor and a concrete verb when they make the sentence easier to understand. Before: Configuration of the connection can be performed. After: Configure the connection. Preserve necessary qualifications; shorter is only better when the meaning survives.
Keep terms stable
Choose one term for each concept and use it consistently. Distinguish a sign-in credential from an API token if the product treats them differently. Match official product and interface names. Expand unfamiliar abbreviations on first use.
Set a style hierarchy
Follow the project’s documented decisions first, then its chosen external guide. Record exceptions and examples in a short house style sheet. Google’s guide explicitly provides a reference hierarchy; a team can adapt that pattern to its own domain.
Edit in passes
First check whether the document answers the right question. Next verify facts and sequence. Then improve sentence structure and terminology. Finally check punctuation and formatting. A polished sentence cannot repair a missing prerequisite.
Sources & further reading
Original guidance and examples by TechWriter, informed by these resources.