# Readability Checklist

Use this checklist to ensure writing is clear, concise, and easy to understand.

## Sentence Structure

- [ ] Most sentences under 25 words
- [ ] Active voice preferred over passive ("You can do X" vs "X can be done")
- [ ] One main idea per sentence
- [ ] Vary sentence length for rhythm
- [ ] Avoid run-on sentences

## Paragraph Structure

- [ ] Paragraphs focus on one idea
- [ ] First sentence introduces paragraph topic
- [ ] Paragraphs are 3-7 sentences typically
- [ ] Avoid wall-of-text paragraphs
- [ ] Smooth transitions between paragraphs

## Word Choice

- [ ] Prefer simple words over complex ("use" vs "utilize")
- [ ] Avoid unnecessary jargon
- [ ] Define technical terms before using
- [ ] Consistent terminology throughout
- [ ] Avoid vague words ("stuff", "things", "very")

## Clarity

- [ ] Main point is obvious in each section
- [ ] No ambiguous pronoun references ("it", "this", "that")
- [ ] Acronyms defined on first use
- [ ] Examples support concepts clearly
- [ ] Concrete examples preferred over abstract

## Organization

- [ ] Logical flow from simple to complex
- [ ] Related information grouped together
- [ ] Headings are descriptive and helpful
- [ ] Bulleted lists for multiple items
- [ ] Numbered lists for sequential steps

## Headings

- [ ] Headings describe content accurately
- [ ] Hierarchy is clear (H1, H2, H3)
- [ ] Parallel structure in heading lists
- [ ] Scannable headings aid navigation
- [ ] Avoid overly clever or obscure headings

## Transitions

- [ ] Smooth transitions between sections
- [ ] Connection between chapters clear
- [ ] Signposting guides reader ("First, Next, Finally")
- [ ] Forward and backward references clear
- [ ] Logical progression obvious

## Technical Content

- [ ] Code examples follow explanations
- [ ] Complex code broken into digestible chunks
- [ ] Step-by-step procedures clearly numbered
- [ ] Prerequisites stated upfront
- [ ] Expected outcomes described

## Audience Awareness

- [ ] Appropriate for target skill level
- [ ] Assumes correct baseline knowledge
- [ ] Explains necessary background
- [ ] Doesn't over-explain obvious points
- [ ] Doesn't under-explain complex concepts

## Readability Metrics

- [ ] Flesch Reading Ease score reasonable for technical content (40-60 acceptable)
- [ ] Grade level appropriate for audience
- [ ] Average sentence length reasonable (15-20 words)
- [ ] Passive voice usage minimal (<10%)
- [ ] Adverb usage minimal