// Scores and evaluates documentation readability using Flesch-Kincaid metrics and qualitative analysis. Use when reviewing docs for sentence length, passive voice, jargon, and reading level.
| name | readability-evaluation |
| description | Scores and evaluates documentation readability using Flesch-Kincaid metrics and qualitative analysis. Use when reviewing docs for sentence length, passive voice, jargon, and reading level. |
Hard technique for scoring and evaluating documentation readability.
readability-score script to get objective metricsThe deterministic score provides the baseline. The LLM adds nuance that formulas cannot capture.
Run readability-score.js from the same directory as this skill file. Pass the path to a markdown file as the only argument.
node <skill-directory>/readability-score.js <file.md>
The script:
The script outputs a JSON object with three keys:
{
"overall": {
"fleschKincaidGrade": 8,
"fleschReadingEase": 59.19,
"wordCount": 157,
"sentenceCount": 13,
"avgSentenceLength": 12.1,
"avgSyllablesPerWord": 1.6
},
"sections": {
"Description": {
"fleschKincaidGrade": 7,
"fleschReadingEase": 61.83,
"wordCount": 19,
"sentenceCount": 2,
"avgSentenceLength": 9.5,
"avgSyllablesPerWord": 1.6
}
},
"flags": [
{
"type": "long-sentence",
"section": "Problems",
"line": 9,
"text": "The navigation component which is used across...",
"value": 47
},
{
"type": "long-paragraph",
"section": "Overview",
"line": 5,
"text": "First sentence of the paragraph...",
"value": 7
}
]
}
overall — document-level scores. Use fleschKincaidGrade and fleschReadingEase to assess the whole document against the target thresholds.
sections — per-section breakdown keyed by H2 heading text. Sections with no prose (e.g. only code blocks) are omitted. Compare each section against the thresholds to find problem areas.
flags — specific issues the script detected. Each flag has a type (long-sentence or long-paragraph), the section it belongs to, the line number in the source file (1-indexed), the text of the sentence or paragraph start, and the value (word count for sentences, sentence count for paragraphs).
Use the script output as the starting point for the qualitative pass. Do not report raw numbers alone. Contextualise them:
| Doc type | FK grade level | Reading ease |
|---|---|---|
| Component docs | 8–10 | 60–70 |
| Pattern docs | 8–10 | 60–70 |
| Foundation docs | 8–10 | 60–70 |
| Content guidelines | 7–9 | 65–75 |
| Accessibility standards | 9–11 | 55–65 |
| API/Props sections | 10–12 | 50–65 |
These are targets, not hard rules. Context matters: an accessibility standard discussing ARIA specifications will naturally score higher.
The following checks are performed by the LLM during the qualitative pass. The script does not cover these.
<passive_voice>
Common passive patterns to flag:
Not all passive voice is bad. It is sometimes appropriate, especially in accessibility requirements. Flag it but note when it might be intentional.
</passive_voice>
Flag terms that are:
Common DS jargon to watch for:
<output_format>
━━━ Readability Review ━━━
Deterministic Scores:
Flesch-Kincaid Grade Level: {score} (target: {target range})
Flesch Reading Ease: {score} (target: {target range})
Average sentence length: {words} words
Per-Section Breakdown:
{Section Name}: Grade {score} — {assessment}
{Section Name}: Grade {score} — {assessment}
Findings:
[severity] Section: {name} (line ~{number})
Issue: {description}
Current: "{the text}"
Suggested: "{improvement}"
Summary:
Overall grade level: {score}
Sections flagged: {count}
Long sentences: {count}
Jargon instances: {count}
Unexpanded acronyms: {count}
</output_format>
Evaluates documentation against the team's brand guidelines. Use when reviewing docs for tone, terminology, sentence structure, and phrasing consistency.
Evaluates whether documentation sections have substantive content. Use when checking whether planned sections are complete, thin, placeholders, or missing.
Evaluates grammar, spelling, and formatting in design systems' documentation. Use when checking mechanics like spelling, punctuation, heading hierarchy, and list formatting.
Evaluates documentation against the team's brand guidelines. Use when reviewing docs for tone, terminology, sentence structure, and phrasing consistency.
Evaluates whether documentation sections have substantive content. Use when checking whether planned sections are complete, thin, placeholders, or missing.
Evaluates grammar, spelling, and formatting in design systems' documentation. Use when checking mechanics like spelling, punctuation, heading hierarchy, and list formatting.