Readability

A grade-level estimate for your manuscript using variants of the standard readability formulas. The local, in-app counterpart to the Rust Readability report.

readability report card

What it measures

Two independent grade-level estimates computed from variants of the standard English-language readability formulas: Coleman-Liau (which counts characters per word and sentences per 100 words — a good measure that ignores syllable estimation) and Gunning Fog (which counts sentence length and the fraction of "complex" words, defined as words of three or more syllables). Each formula returns a number that maps roughly to a US school grade level — a Coleman-Liau of 8.6 means the average student in the second half of eighth grade should be able to follow the prose fluently.

The card renders each formula with its grade-level number and a colored bar showing the value's position on a 0–20 scale (green if grade 8 or under, amber if 9–13, red if 14+). The two formulas usually agree within a grade level. When they disagree — Coleman-Liau at grade 7 but Gunning Fog at grade 12, for instance — your prose has an unusual mix that one of the two formulas is misreading. Typically that means short paragraphs with polysyllabic vocabulary (Fog spikes because of the syllable count; Coleman-Liau stays low because of the short sentences) or the reverse: long sentences with simple monosyllables (Fog reads low; Coleman-Liau reads high).

Below the two grade rows the card also shows a readability grade label — a single word summarizing where the prose sits ("Simple", "Standard", "Advanced", "Expert"). The label is colored green for the accessible tiers and amber for "Expert", which is the analyzer's way of saying "this reads like literary or academic prose, not popular fiction."

The pinned Sentence analysis card at the top of the Reports panel computes a fuller battery of seven readability formulas — Flesch ease, Gunning Fog, Coleman-Liau, Flesch-Kincaid, ARI, SMOG, Dale-Chall — from a different code path (the external Rust engine). This card is the more compact recomputation from the LLM-side analyzer using two of those formulas. Two independent computations that agree give you high confidence in the grade level. If this card's numbers match Sentence analysis's corresponding rows within a grade, treat the number as solid.

Why it's useful

Grade level is a rough proxy for reading effort. It doesn't measure whether prose is good — plenty of grade-4 prose is unreadable and plenty of grade-14 prose is masterful — but it does measure how much cognitive lift a reader has to do to follow the sentence structure. A book pitched at general adult readers that comes back at grade 14 is going to feel like homework to the intended audience; a middle-grade novel that comes back at grade 3 is probably underwriting for its age band.

The typical scenario: you've written what you think is a commercial thriller and you want to check whether the prose is accessible enough for airport-bookshop readers. Popular commercial fiction typically sits in the grade 6–9 range. If your Coleman-Liau is 11 and your Fog is 13, you've written literary fiction with a thriller plot — which is a legitimate book, but if you were pitching mass-market you have a mismatch you should either lean into or fix.

The other useful application is quality control across a revised manuscript. If your first draft sits at grade 8 and your latest revision has drifted to grade 11 without you meaning to, that usually indicates you've been elaborating rather than tightening on your revision passes — sentences got longer, clauses stacked up, vocabulary got fancier. The number surfaces that drift.

For nonfiction and academic writing the number reads differently — you're not trying to hit a low grade level, you're trying to hit the level appropriate for your audience. A trade nonfiction book aimed at educated general readers should land around grade 10–12; a peer-reviewed article expects grade 14+. Use the number the same way: as a check on whether you're where you meant to be, not as a target to minimize.

How to read it

The card renders as a compact list with two horizontal-bar rows. Each row has the formula name on the left, a fill bar in the middle showing the value's position on the 0–20 grade scale (color-coded green/amber/red by grade band), the numeric value in bold, and a small hint pill on the right showing "grade N" as a rounded integer.

Below the two rows is a single Audience line with the readability grade label rendered as a pill — green for "Simple" or "Standard", amber for "Expert". The label answers "what audience is this pitched at?" in one word, more coarsely than the numeric grade but easier to communicate ("this reads at Expert level" is more actionable than "this reads at Coleman-Liau 13.2" for a lot of authors).

The collapsed card summary in the reports rail shows the Coleman-Liau number, the Gunning Fog number, and the grade label side by side ("Coleman-Liau 9.1 · Fog 10.4 · Standard"), so you can see the state of the readability signal at a glance from the panel without expanding. When the two formulas agree within a grade you can trust the summary; when they diverge by more than two grades, expand the card and check which formula the Sentence analysis hero panel is closest to — that's usually the more accurate one for the specific mix of your prose.

Treat any bar that's amber as "worth thinking about" and any bar that's red as "consciously check that this is the audience you meant to pitch at". Neither is an error condition on its own.

When to ignore it

Genre matters enormously here. Literary fiction is supposed to read at higher grade levels — long sentences, complex vocabulary, subordinated clauses are the tools of the trade. If you're writing Marilynne Robinson and your Coleman-Liau is 12.5, that's the correct number. Children's books are supposed to read at lower grade levels; if you're writing a middle-grade novel and your Fog is 4.2, that's also the correct number. The formulas are audience-agnostic; you're not.

Nonfiction that leans on technical vocabulary (medical writing, legal writing, hard science) will always come back at grade 14+ regardless of how skillfully written it is, because the vocabulary is inherently polysyllabic. Don't try to bring the number down by simplifying words your reader needs to understand the subject — the reference audience already has the vocabulary, and simplifying it makes the prose worse, not better.

Dialogue-heavy manuscripts skew the numbers downward because dialogue is naturally shorter and simpler than narration. If your book is 60% dialogue by line count and the report says grade 6, you're probably not actually writing at grade 6 — you're writing conversational dialogue that pulls the average down while your narration is at grade 9. Split the manuscript by dialogue vs narration if you want the numbers to reflect the "real" prose grade.

And any manuscript under 5,000 words is too short for the numbers to be stable. Formula-based readability estimates need a decent sample size before they settle; a very short text can produce wildly variable numbers on rewrite. Wait until you're at chapter-count before treating this report as diagnostic.

How to run it

  1. Click Write in the left sidebar and open the document you want to analyze.
  2. Open the right-side rail: click the Reports button in the editor's top toolbar (the bar-chart icon).
  3. In the rail header, click the Reports tab.
  4. Scroll to the Readability card under the Stylistic heading.
  5. Click the card to expand it. First-time runs take 5–20 seconds; a spinner in the header shows while the LLM streams. Cached results render instantly. Re-run forces a fresh pass.
  6. The card renders four grade cards — Flesch ease, F-K grade, Coleman-Liau, ARI — plus an estimated reading time and a Difficult paragraphs list. Each row shows a difficulty pill (hard / difficult / slightly) with a matching swatch and the offending excerpt. The collapsed summary shows Coleman-Liau, Gunning Fog, and the overall grade level.