clear-writing

name	clear-writing
description	Quality principles for clear, readable prose. Combines Excellent Writing (15 principles for density), Plain Language (active voice, short sentences), and Information Mapping (scannability, chunking). Use during drafting and editing for maximum clarity.

Clear Writing Principles

Three complementary approaches to writing that readers understand immediately.

1. Excellent Writing (15 Principles)

Core: Less is more. Every word earns its place.

Essential Principles

Principle	Rule	Example
No filler	Remove empty words	"really important" -> "critical"
Info density	Every sentence adds new info	No repetition
Economy	Shorter words win	"utilize" -> "use"
One example	If one makes the point, stop	Don't over-prove
Direct statements	State what things do, not that they're important	"X enables..." not "X is important because..."
Start with meat	Lead sections with specifics	No "let me explain why this matters"

Detection Patterns

Cut these phrases:

• "It's worth noting that..." -> Just state it
• "In order to..." -> "To..."
• "At this point in time" -> "Now"
• "Due to the fact that" -> "Because"

2. Plain Language (4 Rules)

Core: Readers understand immediately - no rereading required.

The Rules

1. Active voice (>80%): "The test caught the error" not "The error was caught by the test"
2. Short sentences (<25 words avg): Split long sentences at "and", "but", "because"
3. No unexplained jargon: Define on first use or use simpler term
4. Clear verbs: "decide" not "make a decision", "use" not "utilize"

Quick Fixes

Weak	Strong
utilize	use
facilitate	enable
make a decision	decide
perform analysis	analyze
advance planning	planning

3. Information Mapping (4 Pillars)

Core: Optimize for how humans actually read (F-pattern, 5-9 chunk limit).

The Pillars

1. Chunking: 5-9 items per list; >9 -> create categories
2. Labeling: Descriptive headings, not "Introduction" or "Section 2"
3. Visual hierarchy: No skipped heading levels (H1->H3 without H2)
4. F-pattern optimization: Front-load important info, keywords at paragraph starts

Scannability Targets

Content Type	Paragraph Length	Heading Frequency
Website	2-4 sentences	Every 3-4 paragraphs
Documentation	4-6 sentences	Every 5-6 paragraphs
Books	5-8 sentences	Section-based

Quick Quality Check

Before publishing, verify:

• Active voice >80%
• No sentences >35 words
• No filler words
• Lists chunked (5-9 items max)
• Headings descriptive
• Important info in first 2 paragraphs

Integration with Structured Writing

Structured Writing -> What to say and in what order
Clear Writing -> How to say it readably

Apply clear writing principles AFTER structure is set.

@import ./content.md (full principles with examples)