Readability (Rust)

The four standard readability formulas plus a list of difficult paragraphs. The Rust-native counterpart to the in-app Readability report.

Endpoint: /readability — no word cap; runs on the full manuscript.

readability-rust report card

What it measures

Four independent grade-level formulas, each derived from a different combination of surface features of the prose:

  • Flesch Reading Ease — 0–100 scale; higher = easier. Uses sentence length and syllables per word. Most popular fiction lands in the 60–70 range; academic writing sits 30–50; children's books above 80. Values above 100 are possible for very simple text and are not a bug.
  • Flesch-Kincaid Grade — US grade level. Uses the same inputs as Flesch Ease but expresses the result as a grade rather than a 0–100 score. 6–9 for most popular fiction, 9–12 for literary, 12+ for academic and technical.
  • Coleman-Liau — grade level; character-based rather than syllable-based (uses average letters per word and sentences per hundred words). More reliable on text with unusual syllable structures (loanwords, coinages, proper nouns).
  • Automated Readability Index (ARI) — grade level; a simple character-and-word-count formula designed for real-time computation. Fastest of the four but has the most variance on short samples.

Alongside the four grade numbers, the endpoint returns an estimated reading time based on a typical reading speed of ~250 words/minute, and a difficult paragraphs list — every paragraph in the manuscript ranked by a composite difficulty score, each labelled by tier: easy, slightly difficult, difficult, or hard.

This endpoint has no word cap — it runs on the full manuscript no matter how long. That's a deliberate choice; readability numbers are only meaningful at scale, and truncating to save compute would make chapter-by-chapter comparison unreliable.

Why it's useful

Four independent formulas from different mathematical traditions. If they all agree, the grade level is solid — you can trust that as a working answer to "what reading level is my prose?" If they disagree by more than 1–2 grades, that disagreement tells you something specific about your prose. Long words plus short sentences will make Flesch-Kincaid say one thing and Coleman-Liau say another; short words plus long sentences will produce the opposite disagreement. Reading the four numbers side-by-side is how you catch that.

For most authors the interesting question isn't the absolute grade level — you already know roughly where your prose sits. It's the difficult-paragraph list. That list is your actionable output: fifteen or twenty specific paragraphs the analyzer flagged as substantially harder than the rest of the book, each with a clickable jump-to-editor. If a paragraph on the list is one you wanted to be difficult (the climactic reveal, the philosophical aside, the dense character monologue) — leave it. If it's one you meant to be transparent (a description of setting, a plot mechanical) — the flag is telling you to rewrite.

Cross-check against Readability (in-app), which uses a partially different set of formulas (Dale-Chall, SMOG, Gunning-Fog). When both reports agree the prose is grade 8, the grade is grade 8.

How to read it

The /readability data appears as the Readability block just below the four header stat tiles — its own titled section on a white background with a subtle top border. Inside, the four formulas render as horizontal scale bars stacked vertically:

  • Flesch ease (blue bar) — fills from 0 to 1 (value ÷ 100)
  • Flesch-Kincaid (violet bar) — fills from 0 to 1 (value ÷ 20)
  • Coleman-Liau (emerald bar) — fills from 0 to 1 (value ÷ 20)
  • ARI (orange bar) — fills from 0 to 1 (value ÷ 20)

Each bar has its label on the left, the coloured fill in the middle, and the numeric value (mono, tabular, 1 decimal) on the right. The color coding is decorative — the bars are colored to keep the four formulas visually distinct, not to encode a green/amber/red verdict. Interpret the number against your target genre, not the color.

Below the bars is a small italic caption line: Reading time: N — the estimated total reading time in hours and minutes for a typical reader.

The difficult-paragraph list feeds the Difficult paragraphs collapsible issue list at the bottom of the panel (with a red dot). Each row shows an excerpt of the paragraph (line-clamped to 2 lines) plus a meta line with the difficulty tier ("easy" / "slightly difficult" / "difficult" / "hard"). Click any row to jump to that paragraph in the editor and see it highlighted via the shared editor decoration layer (the difficult layer). Click again to deselect and clear the paint.

When to ignore it

As with the other readability report, genre matters more than absolute grade. Literary fiction is supposed to read at higher grade levels — that's part of the register. Cormac McCarthy scores around grade 11–13; nobody is going to fix him. Children's fiction is supposed to read at lower grade levels — grade 3–5 is the target. Academic writing sits above grade 14 by design. The four numbers are only meaningful compared to your target audience, not compared to some universal ideal.

Second: dialogue drops the grade level significantly. Speech is naturally shorter and more conversational than narration, so a dialogue-heavy chapter will score easier than a narration-heavy one in the same book. That's not the chapter being simpler — that's the form of dialogue. If you're comparing chapters within a book, weight the difference.

Third: proper nouns inflate grade level because most formulas count them as if they were regular words. A fantasy novel with names like "Alagondainesse" and "K'ulthum" will read as higher grade than an identically-structured novel with names like "Jane" and "Tom". The Coleman-Liau and ARI formulas are less affected than Flesch-Kincaid because they're character-based rather than syllable-based; if your fantasy names are throwing your grade level, weight those two more heavily.

Finally, formulas cannot see meaning. A book of nonsense syllables at appropriate sentence and word lengths will read as grade 5. A book of philosophical density in short sentences and common words (much of Meditations, most Zen koans) will read as grade 4. The formulas measure surface features only; use them as one input, not as the answer.

How to run it

  1. Click Write in the left sidebar and open the document you want to analyze.
  2. Open the right rail: click the Reports button (bar-chart icon) in the editor's top toolbar.
  3. In the rail header, click the Rust tab.
  4. All 8 Rust endpoints run in parallel on tab open — typically completes in 2–5 seconds. There is no card to click; everything renders in one composite panel.
  5. The readability data appears as the Readability block just below the four header stat tiles. Each of the four formulas (Flesch ease, Flesch-Kincaid, Coleman-Liau, ARI) renders as its own horizontal scale bar with the numeric value on the right. The estimated reading time appears as small italic text under the bars.
  6. The difficult-paragraph list feeds the Difficult paragraphs collapsible issue list at the bottom of the panel — click an item to jump to that paragraph in the editor and see it highlighted.