Keep average sentence length under 20 words

What this check does

Sums every word on the page and divides by the number of sentences. The result is the mean words-per-sentence. The check fails above 20.

This is the companion check to Long sentences — that rule looks at the long tail, this one looks at the average. You can fail one without failing the other.

Why it matters

Sentence length is the single biggest dial on reading speed, on every measurement scale ever published:

• Plain-language guidelines (US federal, EU) target an average of 15–20 words.
• Hemingway Editor flags pages where the average sentence is “hard to read” — the threshold is around 21 words.
• Yoast SEO sets its “good” cutoff at 20.
• Mobile screens wrap a 22-word sentence to roughly four lines at 16px / 360px. Four lines is the threshold where eye-tracking studies see scanning behavior take over from reading.

The rule isn’t that every sentence has to be short — it’s that the average has to be conversational. Vary the rhythm: a 5-word punch line after a 25-word setup is fine and good prose. A page of 25-word sentences is exhausting.

How to fix it

The fix is identical to Long sentences: find the longest sentences and split them. Because this is a mean, even cutting your top 10% of sentences pulls the average down meaningfully.

Pattern: split with periods, not commas. Most over-long sentences are two or three real sentences stuck together with commas or “and”:

Before (28 words):
We rewrote the audit engine in TypeScript over the summer, which let us drop
the legacy PHP stack entirely, and we now run the whole thing on a single
Bun process.

After (10 + 9 + 7):
We rewrote the audit engine in TypeScript over the summer. The legacy PHP
stack is gone. The whole thing now runs on a single Bun process.

Pattern: introduce variety. A page of uniform 19-word sentences is technically passing but feels mechanical. Mix:

We ship every Friday. The deploy takes nine minutes — about half of that is
the Astro build, which we haven't optimized yet. Then it's live.

Four sentences: 4 words, 22 words, 10 words, 2 words. Average: 9.5. Reads naturally.

Pattern: drop filler. Most long sentences have a fifth of their words doing nothing:

Before (24 words):
It is important to note that the integration with GA4 currently only supports
properties that have been linked through the explicit per-website connection flow.

After (12 words):
GA4 only works for properties linked through the per-website connection flow.

“It is important to note that,” “the fact that,” “in order to,” “at this point in time,” “due to the fact that” — search and delete.

Pattern: convert lists. Three coordinated clauses in a sentence almost always read better as bullets. See the example on the Long sentences page.

Tools. Same as the long-sentences page: Hemingway, Yoast, textstat, MS Word readability stats. For CI, fail builds when the average crosses 20:

import textstat from "textstat";

const avg = textstat.avgSentenceLength(pageBody);
if (avg > 20) throw new Error(`Avg sentence length ${avg} > 20`);

Frequently asked questions

My page is a technical reference — do I really need to be at 20?

Technical reference pages are an exception. API docs, schema descriptions, and command-line man pages can legitimately have higher averages because they prioritize precision over flow. For marketing pages, blog posts, product copy, support articles, and onboarding flows, the 20-word rule is right.

What’s a good target if 20 is the ceiling?

15–18 words on average is the sweet spot. The plain-language guidelines say “around 15”; most professionally edited blog posts land at 16–18. Below 10 starts to feel staccato unless you’re going for a specific voice.

Does varying sentence length matter, or just the average?

Both. The average is what the check measures, but rhythm matters separately — a page where every sentence is exactly 17 words reads worse than one with 8/22/12/4/19. Vary the lengths and the average takes care of itself.