Reading level
The target we write to, how a readability score is calculated, and why the score is a diagnostic rather than the goal.
The rule
Write so that a reader who is not concentrating can follow it the first time. Measure the result, then fix the sentences the measurement points at. Never fix the score.
Readability formulas count syllables, words per sentence and sometimes word frequency. They are cheap, reproducible and extremely blunt. What they measure correlates with comprehension; what they do not measure is whether the reader can use the sentence, which is the thing health content is for.
Three properties of the formulas that matter in practice:
- They cannot see meaning. "Take two of the small white ones before food" and "Take two of the large blue ones after food" score identically. One of them may be dangerous.
- They punish necessary words. "Hydrochlorothiazide" and "appointment" both raise the score. One of them can be replaced and one cannot, and no formula knows which.
- They can be gamed trivially. Chopping every sentence at the comma lowers the score and raises the reading effort, because the reader now has to reassemble the relationship the comma expressed.
So a score is a smoke alarm: useful because it goes off, useless as a measure of how well you cook.
The target
We write to roughly the level of a UK national newspaper's news pages. The common shorthand for this is "around age 9 to 11 reading level", and it is the level public-sector health guidance in the UK generally aims at. Two qualifications, both important:
- It is a ceiling for the ordinary case, not a floor to hit. Simpler is usually better; there is no prize for arriving exactly at the target.
- It is suspended for safety-critical copy. An
urgentmessage is written for speed and unambiguity. If the clearest possible instruction scores badly, the instruction wins.
Approved / Rejected
Do
Don’t
Do
Don’t
The second pair is the gaming failure. The rejected version scores better on every formula and is harder to read, because four short sentences have destroyed the causal link the reader needed.
Do
Don’t
Patterns
Diagnosing a bad score. The score tells you a page is hard; these five checks tell you where.
Find the longest sentence
Read it aloud. If you run out of breath, it has more than one idea in it. Split it at the idea boundary, not at the comma.
Find the longest word that is not a clinical term
That word almost always has a shorter, commoner twin: "administer" is "take", "commence" is "start", "utilise" is "use", "prior to" is "before".
Count the words before the main verb
Health copy tends to open with a subordinate clause. "If your readings have been higher than usual over the last few days, then…" is the shape to watch for. Move the main clause first.
Look for the nominalisations
"Make an application" is "apply". "Provide an indication" is "show". Turning verbs into nouns is the single largest source of unnecessary difficulty in institutional writing.
Read the first sentence on its own
If it does not contain the answer, no readability score will save the page.
Sentence shapes that read easily
Subjectverbobject.Consequence.
Your
measurewasvalue. That iscomparison.
If
condition,action.
When to break the target on purpose
Any
urgentmessage · any dosing instruction · any legally required wording · any sentence where the plainer version is ambiguous.
Banned words
The practices below are not banned outright. They are banned as substitutes for editing.
| Banned practice | Why | Do instead |
|---|---|---|
| Reporting a readability score as a quality metric | It measures sentence and word length, not comprehension. | report what you changed |
| Splitting sentences to lower a score | Destroys the relationships between ideas. | split at idea boundaries only |
| Deleting a clinical term because it is long | The reader needs to recognise it elsewhere. | give the term and translate it |
| Setting a score as an acceptance criterion | It becomes a target and stops being a measure. | use it as a smoke alarm |
| Publishing a score we have not generated | It would be a measured number that is not measured. | say there is no score yet |
Applying the target to urgent copy | Clarity beats simplicity when somebody must act now. | write for speed |
Related components
ReadingLevelis the readout for a sample of copy. It is a P2 component and is not implemented; when it is, it reports the score and the longest sentence, because the second is the actionable half.Termis the sanctioned way to keep a long clinical word without paying its comprehension cost.CareCardandAlertBannerare the two surfaces where the target is most often suspended, and correctly so.ResultCardis the surface where the target matters most, because it is read under stress.
Implement <ReadingLevel> and wire a readability pass into pnpm run check so
that content pages report their longest sentence. No score should be published
for this documentation until that script exists and has run.
Inclusive content
The language choices about age, disability, gender, ethnicity, body and skin decide whether a health app is written for everybody or for a default reader.
Registry & distribution
opsinjs is distributed as a shadcn-spec registry rather than as an npm package, and this is what that decision buys and what it costs.