BMAD-METHOD/expansion-packs/bmad-technical-writing/checklists/readability-checklist.md

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