| name | writing-clearly-and-concisely |
| description | Write clear, forceful prose for humans. Based on Strunk's Elements of Style. Use for documentation, commit messages, error messages, reports, UI text, or any writing a human will read. Covers active voice, omitting needless words, concrete language, and AI writing patterns to avoid. |
| metadata | {"hermes":{"tags":["writing","documentation","style","clarity"],"related_skills":["clean-code","humanizer","pd"]}} |
Writing Clearly and Concisely
Overview
Write with clarity and force. Based on William Strunk Jr.'s The Elements of Style (1918).
When to Use
- Documentation, README files, technical explanations
- Commit messages, pull request descriptions
- Error messages, UI copy, help text, comments
- Reports, summaries, or any explanation
- Editing to improve clarity
If you're writing sentences for a human to read, use this skill.
Core Rules
Active Voice
- "The committee decided" not "It was decided by the committee"
- "The app crashed" not "An error was encountered"
- Active is shorter, clearer, more forceful
Omit Needless Words
- "Because" not "due to the fact that"
- "Now" not "at this point in time"
- "Can" not "has the ability to"
- "If" not "in the event that"
- "About" not "with regard to"
Every word that adds nothing is a word wasted.
Concrete Language
- "3 million lines of code" not "a substantial amount of code"
- "Takes 200ms" not "highly performant"
- "Opens in 3 seconds" not "seamless user experience"
Prefer definite, specific, concrete language. Details are convincing.
Positive Form
- "Bad" not "not good"
- "Forget" not "fail to remember"
- "Ignore" not "pay no attention to"
- "Honest" not "not dishonest"
State what IS, not what ISN'T.
One Paragraph Per Topic
- Begin each paragraph with a topic sentence
- Each paragraph = one idea
- Transition between paragraphs logically
Keep Related Words Together
- "He noticed a large stain in the rug" not "He noticed a stain in the rug that was large"
- Keep modifiers close to what they modify
Place Emphatic Words at End
- "This duty we must fulfill" not "We must fulfill this duty"
- End with what matters most
AI Patterns to Avoid
- Puffery: pivotal, crucial, vital, testament, enduring legacy
- Empty "-ing" phrases: ensuring reliability, showcasing features, highlighting capabilities
- Promotional adjectives: groundbreaking, seamless, robust, cutting-edge
- Overused AI vocabulary: delve, leverage, multifaceted, foster, realm, tapestry
- Formatting overuse: excessive bullets, emoji decorations, bold on every other word
Be specific, not grandiose. Say what it actually does.
Quick Reference
| Say this | Not this |
|
