Writing Clearly and Concisely

Overview

Write with clarity and force. This skill covers what to do (Strunk) and what not to do (AI patterns).

When to Use This Skill

Use this skill whenever you write prose for humans:

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

Elements of Style

William Strunk Jr.'s The Elements of Style (1918) teaches you to write clearly and cut ruthlessly.

Elementary Rules of Usage (Grammar/Punctuation)

1. •Form possessive singular by adding 's
2. •Use comma after each term in series except last
3. •Enclose parenthetic expressions between commas
4. •Comma before conjunction introducing co-ordinate clause
5. •Don't join independent clauses by comma
6. •Don't break sentences in two
7. •Participial phrase at beginning refers to grammatical subject

Elementary Principles of Composition

1. •One paragraph per topic
2. •Begin paragraph with topic sentence
3. •Use active voice
4. •Put statements in positive form
5. •Use definite, specific, concrete language
6. •Omit needless words
7. •Avoid succession of loose sentences
8. •Express co-ordinate ideas in similar form
9. •Keep related words together
10. •Keep to one tense in summaries
11. •Place emphatic words at end of sentence

Core Principles Explained

Use Active Voice

Active voice is direct and vigorous.

Passive: The report was written by the team. Active: The team wrote the report.

Passive: The error was caused by invalid input. Active: Invalid input caused the error.

Put Statements in Positive Form

Say what something is, not what it isn't.

Weak: He was not very often on time. Strong: He usually came late.

Weak: The function does not accept null values. Strong: The function requires non-null values.

Use Definite, Specific, Concrete Language

Prefer the specific to the general, the definite to the vague, the concrete to the abstract.

Vague: A period of unfavorable weather set in. Concrete: It rained every day for a week.

Vague: The system experienced performance issues. Concrete: Response time increased from 50ms to 3 seconds.

Omit Needless Words

Vigorous writing is concise. Every word should tell.

Keep Related Words Together

The subject and principal verb should not be separated by a phrase or clause that can be moved.

Separated: The dog, after running through the mud and swimming in the pond, came into the house. Together: After running through the mud and swimming in the pond, the dog came into the house.

Place Emphatic Words at End

The end of a sentence is its most emphatic position.

Weak: Humanity has barely begun to explore space, since the Moon landings. Strong: Since the Moon landings, humanity has barely begun to explore space.

AI Writing Patterns to Avoid

LLMs regress to statistical means, producing generic, puffy prose. 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: Before and After

Bottom Line

1. •Use active voice
2. •Be specific and concrete
3. •Cut needless words
4. •Put the punch at the end
5. •Avoid AI vocabulary

When in doubt, read it aloud. If it sounds inflated or awkward, revise.