writing-clearly-and-concisely
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.
When & Why to Use This Skill
This Claude skill enhances the clarity and impact of your writing by applying Strunk's classic principles of style. It focuses on eliminating wordiness, utilizing the active voice, and ensuring every word serves a specific purpose, transforming verbose drafts into vigorous, professional prose suitable for technical and business environments.
Use Cases
- Refining technical documentation and API references to ensure instructions are concise, direct, and easy to follow.
- Polishing git commit messages and pull request descriptions to be brief yet highly informative for better codebase maintainability.
- Simplifying complex business reports and executive summaries by removing redundant phrases and 'filler' words to highlight key insights.
- Improving the clarity of error messages and UI microcopy to provide a better user experience through specific and concrete language.
- Streamlining internal communications and emails to ensure the main point is communicated effectively without unnecessary preamble.
| 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.