| name | writing-clearly-and-concisely |
| description | Use when writing documentation, commit messages, error text, explanations, reports, or summaries. Applies Strunk's principles for clear, vigorous prose. Triggers: writing human-readable content, verbose text, unclear explanations. |
Writing Clearly and Concisely
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.
