writing-clearly-and-concisely
Writing Clearly and Concisely
Write with clarity and force: say what you mean in as few words as the meaning and the voice allow. Strunk tells you what to do; the AI-pattern list tells you what not to do. The Voice rule decides when they conflict.
Use it for any prose a human reads: docs, READMEs, commit and PR messages, error and UI text, comments, reports, and edits of existing drafts.
Voice outranks Rule 13
Strunk's "omit needless words" means words that do no work. Personality does work. When you edit someone else's text, especially a personal blog post:
- Keep the register. Never "professionalize" casual prose. A rambling sentence gets tighter, not more formal.
- Keep profanity, humor, asides, deliberate repetition, all-caps emphasis, and punchlines. Swearing is emphasis, not filler. If a profane sentence must change, keep the swear word.
- Keep words the author chose on purpose, even ones on the AI-pattern list below. That list is for text you write; it is not a find-and-replace list for a human's draft. If the author writes "leverage", leave it.
- Cut filler, not personality: hedges, throat-clearing, doubled phrases, restated points, "the fact that", "there is/are ... that/who".
For the jeffbaileyblog Hugo site, read hugo/content/prompts/writing-style.md sections "Voice and Tone", "Human writing checks", and "Things to NOT Do" before editing. They extend these rules (no emdashes, no contrast-framing crutch, no over-signposting). Its punctuation rules apply to the sentences you rewrite; that is style, not voice. Outside the blog, keep the document's own punctuation conventions.