writing-clearly-and-concisely

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 | |