Plain-English A to Z
The canonical clinical-to-plain vocabulary, the rule for choosing a replacement word, and the machine-readable list every product and Term instance shares.
The rule
This page is canonical for plain language. Every other page in this system
links here rather than restating a word choice, and assert-ia.mts enforces that
they do not restate it. If a clinical term appears in a product built on opsinjs,
its replacement is the one on this page.
The rule for choosing a replacement is four tests, applied in order. A candidate must pass all four.
- Would someone say it out loud? "Raised" passes. "Elevated" does not. Read the sentence aloud to somebody who does not work in health; if they would not use the word in conversation, it is not the replacement.
- Does it lose anything the reader needs? Plain does not mean vague. "Water pill" is plainer than "diuretic" and it is wrong, because the reader will not recognise it on the box. When plainness costs accuracy, the answer is both words, not the plainer one.
- Will they meet the clinical term elsewhere? If the word appears on their prescription, their letter, their portal or their monitor, they need to recognise it. Give the clinical term and the explanation, in that order, once, and then use the plain form.
- Is it the same word every time? Synonym variation is a comprehension cost with no benefit. One clinical term maps to exactly one plain replacement across the whole product, which is precisely what makes this list worth having.
Provenance
Every definition in this list is written from scratch for opsinjs. We do not copy the NHS A to Z or any other Crown-copyright material, and we do not copy definitions from a dictionary or a manufacturer's leaflet. We cite sources; we never paste them. If a definition here looks like one you have seen elsewhere, that is a bug and we would like to know.
This matters beyond licensing. A definition lifted from a clinical source is usually written for a clinical reader and carries a register the whole list exists to remove.
Where the data lives
The list is a data file, not prose. It is authored in tokens/glossary.json,
emitted into the generated reference, indexed by search, and resolved at runtime
by Term. One record per clinical term, and each record carries the clinical
term, the plain replacement, an original one-sentence definition, optional
search synonyms and an optional note about where the reader will meet the
clinical word. The record shape and how to add to it are on
Glossary.
Approved / Rejected
Do
Don’t
Do
Don’t
Do
Don’t
Do
Don’t
The last pair is the one that catches careful writers out. Deleting the clinical word made the sentence plainer and made it useless: the reader has two inhalers in a drawer and needs to know which one this is. Plainness is in service of the reader's task, not the other way round.
Patterns
Introducing a term the reader will meet on a document
Plain phrase. Your GP might call thisclinical term.
Introducing a term the reader has already met
Clinical termmeansplain explanation in one clause.
A measurement with a named part
Your
measurewasvalue. Thepositionnumber is theplain name for the part.
A medicine
Brand or common name(what it is for). Takedosewhen.
A procedure
Plain name. This meanswhat physically happens, and it usually takesduration.
The list
tokens/glossary.json and flattened into lib/generated/glossary.json, which is also what <Term> reads. Run pnpm run generate.Nothing on this site types a measured number by hand, so an ungenerated table shows this rather than an example.
The list is short and grows one entry at a time, because every entry is written rather than imported. An empty or thin list is the honest state of a vocabulary that is being built properly; see Glossary for how to propose an addition.
Banned words
These are banned as replacements. They are the plausible-looking plain words that make things worse.
| Banned replacement | Why | Use instead |
|---|---|---|
| water pill (for diuretic) | Unrecognisable on the packet. | the medicine's name, plus what it does |
| sugar (for glucose in a result) | Confuses the measurement with the food. | blood sugar, once, then the measure's name |
| bad cholesterol / good cholesterol | A moral frame on a lipid fraction, and readers routinely swap them. | the named fraction, with what a higher figure means |
| tummy | Infantilising, and imprecise across a large area of anatomy. | stomach, or the specific part |
| passed away, lost their battle | Euphemism where clarity is required. | died |
| suffers from, victim of, afflicted by | Frames a condition as an identity or a defeat. | has, lives with. See Inclusive content. |
| the diabetic, the asthmatic | The condition standing in for the person. | a person with diabetes |
| normal | A verdict about the person. See Reference ranges. | your usual range |
Related components
Termis the inline component that renders a clinical word with its plain replacement. It resolves against this list; a term not in the list cannot be rendered, which is deliberate.Glossaryis the filterable A to Z above, and the same data.ResultCard,AlertBannerandCareCardare bound by this vocabulary in every string they carry.DisclaimerNoteis the one place where a legally-shaped sentence is permitted, and even there it is written in this register.