Readability scores - Flesch Reading Ease, Flesch-Kincaid Grade, Gunning Fog - were built on prose. Technical documentation breaks their assumptions: a line of code counts as a "sentence", identifiers count as "syllables", and your README's grade level quietly becomes nonsense. Here is how the main options compare.
The Tools
| Tool | What it gives you | Code handling |
|---|---|---|
| Word / Google Docs built-ins | Flesch-Kincaid grade | None - code counts as text |
| Hemingway Editor | Grade level + visual density | None - paste code and the grade tanks |
| Hemingway Editor Plus | ~$10/mo, AI rewrites | None |
| Online Flesch calculators | Raw score | None |
| Lint readability analyzer | Flesch family scores | Code lines excluded from the math |
Why Excluding Code Matters
A README that is 60% prose and 40% code will score as "very difficult" on any prose-based tool - not because the writing is bad, but because kubectl get pods -o jsonpath=... reads as an unreadable sentence. The practical failure: writers then "simplify" good documentation to please a number.
A code-aware analyzer splits the document first. Prose gets scored; code blocks, commands, and inline identifiers are skipped. The resulting number describes the thing you can actually edit - your sentences.
How to Use Scores Without Obsessing
- Target range, not a number: for developer docs, Flesch Reading Ease 40-60 ("difficult" to "plain English") is normal and fine
- Watch the trend: a jump from 52 to 30 after adding a section is a signal; the absolute number is not
- Sentence length beats syllable counting: for technical audiences, long sentences are the real killer - fix those first
Try Lint's readability analyzer - deterministic formulas, code excluded, free tier, no signup. Pair it with the grammar checker on the same text.
Top comments (0)