| name | readme-writer |
| license | MIT |
| description | Measure and improve the reading level of any prose — docs, READMEs, emails, proposals, specs, plans. Scores Flesch-Kincaid grade level and top-1000 vocabulary coverage with real scripts instead of estimates. Triggers on 'readability', 'reading level', 'grade level', 'Flesch-Kincaid', 'plain language', 'make this easier to read', 'simplify this writing', 'too dense', 'ESL-friendly', and on 'write readme', 'improve readme', 'readme review', 'documentation writing'. |
Readability and README Writing
Two jobs. The common one: measure and improve reading level in any prose —
a doc, an email, a proposal, a spec, a plan. The narrower one: structure a
README.
Always Measure — Never Estimate
Syllable counts cannot be eyeballed accurately across a document. Reporting a
Flesch-Kincaid score without running the script is guessing. Run it.
cat FILE | ruby scripts/flesch_kincaid.rb
Works on any text, not just markdown — pipe in an email draft, a section of a
doc, a paragraph pasted into a heredoc.
Target: grade level 11 or below. Technical terms inflate the score, and
that's fine — the goal is to keep the surrounding prose clear so the technical
content stays accessible.
Revise, then re-measure. Focus revision on:
- Shortening sentences (not dumbing down terminology)
- Replacing complex connectors with simple ones
- Breaking multi-clause sentences into two
Report the before and after scores.
Vocabulary Coverage
Many readers of technical writing are not native English speakers.
cat FILE | ruby scripts/vocabulary_profiler.rb
Aim to raise the percentage of words in the top 1000 most common English words.
Technical terms lower this number — expected. Keep the non-technical words
simple.
Do:
- Use active voice
- Keep noun phrases short and direct
- Limit embedded clauses to one level of nesting
- Use simple "if/then" conditionals
- Make logical connections explicit with transition words (however, therefore, because)
- Spread information across multiple sentences when needed
Don't:
- Stack multiple modifiers before nouns ("the recently revised standardized testing protocol")
- Rely on mixed or inverted conditionals ("Had she known...")
- Expect readers to infer relationships between ideas
- Pack too many new concepts into a single sentence
- Assume shared knowledge of idioms or cultural references
Flow and Transitions
- Start with concepts, then details. Give readers the "why" before the "how"
- Add transitions between major sections so the piece reads as a narrative, not a list of disconnected blocks
- Create logical progression from high-level to detailed
README Structure
When the document is specifically a README, it flows through these sections:
- What and why — what the package does and why it matters (the "what's in it for me")
- Install and use — how to get started quickly
- Configuration — common options and methods
- Contributing — how to contribute, or a pointer to CONTRIBUTING.md. Notes on the build environment and portability
- Project layout — unusual top-level directories or files, hints for navigating the source
Formatting
Use GitHub-flavored callout blocks to highlight important information:
[!CAUTION]
[!IMPORTANT]
[!NOTE]
[!TIP]
[!WARNING]
- Use bold for key concepts on first introduction
- Use
code for commands, filenames, config keys, and values
- Use concrete, descriptive names for examples ("Invoice Approval" not "Example 1")
Quality Checklist
Bibliography
