writing-prose

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.

Brevity

AI-assisted writing runs longer than the writer would have produced by hand: paragraph after paragraph of plausible-sounding text that says little. Length is itself a tell, and every extra word taxes the reader.

Cut to what you'd write if you had to say it out loud to a busy person. This is not terseness: keep every idea the reader needs, drop the words that carry none. If a cut loses meaning, keep the words. If it only loses padding, cut.

Test: Is this longer than I'd have written without help? If yes, cut.

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?

Punctuation

NEVER use emdashes (—). Use commas, periods, colons, semicolons, or parentheses instead. Rewrite any sentence that seems to need an emdash.

Word Choice

Prefer	Avoid
Short, common words	Jargon, fancy vocabulary
Active voice	Passive constructions
Concrete nouns	Abstract nominalizations
"Use"	"Utilize"
"Help"	"Facilitate"
"About"	"Regarding"

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

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

# Good
Users need to know that...

Burying the Point

# 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

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

# Good
How we handle validation errors...

Weasel Words

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

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

Qualifications Done Right

Qualifications are not weaknesses; they are 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

Principle	Action
Conversational	Would I say this to a friend?
Simple	Ordinary words, short sentences
Bold	Strong claims, qualified precisely
Honest	Simple prose exposes weak ideas
Rhythmic	Sound matches logic
Cut	Delete everything unnecessary