writing-clearly-and-concisely

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:

1. Draft without constraint
2. Replace vague with specific
3. Eliminate needless words
4. Use active voice
5. One topic per paragraph
6. Emphatic words at end

Every word must justify its presence.