84 lines
2.4 KiB
Markdown
84 lines
2.4 KiB
Markdown
# 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
|