---

name: writing-prose description: Use when writing documentation, READMEs, explanations, blog posts, or any prose meant for humans to read

Writing Prose

The Rule

Write like you talk. Then cut.

Every sentence must pass this test: "Would I say this to a friend?" If not, rewrite it.

Core Formula

Usefulness = Correctness × Novelty × Importance × Strength

• Correct: True, but not so vague it says nothing
• Novel: Unknown to reader—surprising or unarticulated
• Important: Actually matters to them
• Strong: As bold as possible without becoming false

These multiply. Zero in any dimension = zero value.

The Process

1. Draft fast — Get ideas down without editing
2. Read aloud — Catches awkward phrasing instantly
3. Cut ruthlessly — Delete weak sentences, abandon weak paragraphs
4. Repeat — Rewrite until no passage feels uncertain

Sentence-Level Checklist

For each sentence ask:

• Would I say this to a friend?
• Can I cut any words?
• Is this the simplest way to say it?
• Does it sound good when read aloud?

Word Choice

Germanic words beat Latinate ones. "Begin" not "commence." "End" not "terminate."

Red Flags

These signal bad prose—rewrite immediately:

• Formal register shift — "The mercurial Spaniard" instead of how you'd actually describe someone
• Hedging stacks — "It could potentially perhaps be argued that..."
• Impressive-sounding emptiness — Long sentences that say little
• Passive voice hiding agency — "Mistakes were made"
• Unnecessary qualifications — Unless they express genuine uncertainty

The Sound-Truth Connection

Writing that sounds good is more likely to be right. Rewriting for flow forces better ideas—you can't consciously make ideas worse while making prose better.

If a sentence sounds clumsy, the idea is probably muddled. Fix the thinking, not just the words.

Anti-Patterns

Formal for Formality's Sake

Copy# Bad
It is imperative that users be made cognizant of the fact that...

# Good
Users need to know that...

Burying the Point

Copy# Bad
After careful consideration of the various factors involved in the
decision-making process, we have determined that the optimal course
of action would be...

# Good
We decided to...

Noun Stacks

Copy# Bad
The data validation error handling mechanism implementation...

# Good
How we handle validation errors...

Weasel Words

Copy# Bad
It is generally believed that this approach is somewhat better.

# Good
This approach is better because [specific reason].

Qualifications Done Right

Qualifications aren't weaknesses—they're precision tools:

• Certainty level: "I think" vs "I'm confident" vs "This is definitely"
• Scope: "In most cases" vs "Always"
• Falsifiability: Makes claims testable

Bad qualification hedges against criticism. Good qualification sharpens the claim.

The Goal: Saltintesta

From Italian "saltimbocca" (leaps into mouth)—ideas should leap into the reader's head. They barely notice the words that got them there.

Simple language lets readers focus on ideas, not parsing prose.

Quick Reference