hjemmesidekongen/ai/writing-clearly-and-concisely

Writing Clearly and Concisely

Apply Strunk's rules for clarity and force. Avoid AI writing patterns.

When to Use

Any time you write prose for humans: docs, READMEs, commit messages, PR descriptions, error messages, UI copy, comments, reports, explanations. If a human reads it, use this.

Key Rules (Most Tasks)

1. Use active voice — "He repaired the car" not "The car was repaired by him"
2. Put statements in positive form — "dishonest" not "not honest"
3. Use definite, specific, concrete language — avoid vague generalities
4. Omit needless words — "the question as to whether" → "whether"
5. Keep related words together — don't split subject from verb unnecessarily
6. Place emphatic words at end of sentence

Full 18 rules (grammar, punctuation, composition): references/process.md

AI Writing Patterns to Avoid

LLMs produce generic, inflated prose. Specific patterns to catch:

• 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
• Filler openers: "It's important to note that", "It's worth mentioning that"
• Hedge phrases: "It should be noted", "It is interesting to note"
• Em dashes (—): Use hyphens (-) or rewrite the sentence. Em dashes are an AI tell — humans rarely type them.

Be specific, not grandiose. Say what it actually does.

See signs-of-ai-writing.md for the full field guide. Reference file index: references/process.md