Skip to main content
SEO & Writing

Readability Scores: What the Numbers Actually Measure

Run any document through a readability tool and you get a number: Flesch 61.5, grade level 8.2, "good". Most developers ship text based on that number without ever asking what formula produced it. That is a mistake, because these scores are narrow, easy to game, and misleading when used outside their original context.

What the formulas actually compute

Every classic readability score is a linear model over two or three surface features of the text. Nothing semantic. Flesch Reading Ease, published in 1948, is:

206.835 - 1.015 x (words per sentence) - 84.6 x (syllables per word)

The Flesch-Kincaid Grade Level reweights the same two variables to map onto US school grades. The SMOG index, which Gunning and McLaughlin built later, drops word length entirely and counts only polysyllabic words per sentence. The Flesch formula is also calibrated for English spelling: it assumes English syllable rules, so it overestimates the difficulty of German and underestimates Finnish, where words are long but syllables are trivial to count.

There is no grammar analysis in any of these. A paragraph of unambiguous nonsense — short words, short sentences — scores better than a paragraph of clear technical prose with two long domain terms per sentence. The formula measures the cost of decoding the words, not the cost of understanding the ideas. Documentation with a bad conceptual structure can score 70 and still be impossible to follow.

Where the scores are genuinely useful

The good use cases are the ones where the two variables the formula tracks are exactly the variables you are trying to control:

  • Regression checking. You edited a paragraph and the score moved from 58 to 34. Something got denser or longer. You may not care about the target score, but you care that the edit made the text harder to parse.
  • Consistency across a document set. Score every page of your docs with the same tool. If one page sits at 30 while siblings are at 60, the outlier usually has a structural problem: run-on sentences, unexpanded acronyms, buried caveats.
  • Screening for walls of text. A score under 30 almost always means sentences over 25 words. That is a smell regardless of audience.
  • Compliance contexts where a regulator, an insurance provider, or a platform explicitly asks for a target grade range. Then the number is contractual, and you meet it deliberately.

Where the number lies to you

Scores mislead when the text is dense but the audience expects density:

  • API references and code-adjacent docs. Method signatures, parameter names, and type annotations are not sentences. Many tools count a code block as a wall of long "words" and tank the score. A perfectly clear API doc can score 25 while being easier to use than prose scoring 70.
  • Legal and medical writing. Plain-language grades are set by contract (often grade 8 or below), but forcing grade 8 through the formula pushes writers toward short slogans that hide required exceptions and exclusions. The formula rewards dropping nuance, which is precisely the information the reader needs.
  • Localized text. Run the same doc in German and in English and you get different numbers for identical meaning, because syllable counting differs per language. Comparing scores across languages is meaningless.

Four failure modes from over-trusting the number

  1. Breaking compound terms. Rewriting "access token refresh" as "token that lets you get a new token" to shorten words makes the text worse and the score better.
  2. Splitting sentences in the wrong place. Two 12-word sentences joined by a comma-heavy clause can read fine, but a mechanical splitter produces fragments with no verb, which lowers comprehension.
  3. Nuking vocabulary. Replacing "initialize" with "start" everywhere in developer docs loses precision. Your audience is not a fifth grader.
  4. Chasing a target grade set by someone else. A marketing stakeholder demands "Flesch 70+" for a whitepaper. You hit 70 and the document now reads like it was written for people who will never buy anything.

A workflow that uses scores without being ruled by them

  1. Write the draft. Ignore the score completely — do not let a 1948 formula shape your first sentence.
  2. Run a readability checker once and record the baseline number. The purpose is regression detection, not grade-school targeting.
  3. If the score dropped sharply after your edit, find out why. Check that sentences did not balloon and that you did not introduce a run of multisyllabic jargon in a single paragraph.
  4. Check density separately: if a keyword-stuffed paragraph is the reason the score fell, a keyword density checker will show you the repetition that often co-causes the score drop and the reader fatigue at the same time.
  5. Before you hit publish, paste the title and description into a SERP snippet preview and read the whole thing as if you had never seen the topic.
  6. Run a final grammar check for agreement and tense errors. No readability formula flags grammar; it flags only average sentence complexity.

Bottom line: a readability score is a cheap tripwire. It is good at telling you "something got denser here" and bad at telling you what your reader will understand. Track the trend, question the outliers, and never let a single number overrule a technical judgement about what your audience actually needs on the page.