What I think about when I edit (2019)

Writing resources & practice

• Multiple commenters recommend classic style guides and technical-writing books, plus Google’s tech-writing courses.
• Several stress that technical-writing advice alone won’t make someone a strong general writer; broader style books that analyze sentence revisions are praised.
• Practice is emphasized: blogging, even writing a book, and forcing tight word counts to learn concision.

Structure, whitespace, and lists

• Whitespace and short paragraphs are widely endorsed for readability, especially on screens; analogy made to blank lines in code.
• Lists are helpful but should only be used when items have similar status; parallel structure in lists is encouraged.
• Coherent narrative flow matters: introduce themes before details and order sections so each idea leads naturally to the next.

Terminology, naming, and acronyms

• Strong consensus: don’t use different names for the same thing or similar names for different things; avoid semantic drift.
• Some advocate a central glossary/dictionary for domain terms; others worry about glossaries being duplicated or misaligned and prefer first-use definitions in context.
• Acronyms should be expanded on first use and not assumed known; lack of definitions causes long-term confusion.
• Disagreement over whether a glossary is the single most important document, but many see high value for low effort.

Passive voice and focus

• Several challenge blanket “avoid passive” advice, arguing passive voice is a useful tool for changing focus or omitting the agent.
• Examples include scientific or neutral descriptions and situations where naming a responsible person is sensitive.
• Others highlight real harms: contractual ambiguity and corporate misuse to obscure responsibility. Nuanced use is generally favored.

Demonstratives, repetition, and word choices

• Many endorse avoiding bare “this/that” and restating the noun, especially at the start of paragraphs, to improve clarity and robustness to edits.
• Some worry repetition feels clumsy but accept it as better than ambiguity.
• Pet peeves include the adverb “just” (seen as dismissive or hand-wavy), heavy future tense in procedures, overused adverbs generally, and unintroduced acronyms.

Audience, clarity, and editing philosophy

• Writers struggle to pick an audience depth; strategies include adding background, using footnotes for deep detail, and framing content with history and narrative.
• Good editing is described as amplifying the original voice, not rewriting from scratch, while staying ruthlessly focused on what the reader needs—even if that means discarding large sections.