| name | writing-clearly-and-concisely |
| description | Apply William Strunk Jr.'s writing principles for clear, vigorous prose. Invoke proactively when writing documentation, commit messages, error text, explanations, reports, summaries, or any human-readable content. |
Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.
Core Principles
Make paragraph the unit of composition: One paragraph per topic. Does each paragraph develop a single idea?
Use active voice: "The committee approved" not "The committee gave approval." Default to active unless actor is unknown or unimportant.
Put statements in positive form: Say what is, not what isn't. "He thought Latin useless" not "He did not think Latin was useful."
Use definite, specific, concrete language: "It rained every day for a week" not "A period of unfavorable weather." "He grinned" not "He showed satisfaction."
Keep related words together: Don't separate subject from verb or verb from object unnecessarily. "In 1865 he published his work" not "He published, in 1865, his work."
Place emphatic words at sentence end: "Although improvements occurred, crime increased" not "Crime increased, although improvements occurred."
Omit Needless Words
Eliminate verbose constructions:
- "the question as to whether" -> "whether"
- "there is no doubt but that" -> "no doubt"
- "used for fuel purposes" -> "used for fuel"
- "he is a man who" -> "he"
- "in a hasty manner" -> "hastily"
- "this is a subject that" -> "this subject"
- "the reason why is that" -> "because"
- "owing to the fact that" -> "since" or "because"
- "in spite of the fact that" -> "though" or "although"
- "call your attention to the fact that" -> "remind you"
- "the fact that" -> (delete or rephrase)
- "as to whether" -> "whether"
Don't bury the main point: "My arrival caused consternation" not "The fact that I had arrived was enough to cause consternation."
Needless Words
case: "In many cases, tests fail" -> "Tests often fail"
character, nature: "Acts of hostile character" -> "hostile acts" "Technical nature" -> "technical"
factor: "Training was a factor" -> "Training contributed" or "They won through training"
feature: Hackneyed word. Avoid as verb.
interesting: Don't announce content is interesting. Make it interesting.
very: Use sparingly. "Very tired" -> "exhausted"
respective, respectively: Usually omissible.
Technical Writing Usage
data: Plural. "These data show" not "This data shows"
fewer vs less: "fewer bugs" (countable), "less memory" (quantity)
while: Means "during the time that." Don't substitute for "and," "but," or "although."
etc.: Don't use after "such as" or "for example." Avoid if reader uncertain what's included.
Edit Ruthlessly
When writing:
- Draft without constraint
- Replace vague with specific
- Eliminate needless words
- Use active voice
- One topic per paragraph
- Emphatic words at end
Every word must justify its presence.