The audience most documentation is actually written for
English is the default language of software documentation, but it is rarely the first language of the people reading it. A developer in Seoul, a support engineer in São Paulo, and a system administrator in Warsaw are all more likely to be reading your README in their second, third, or fourth language than in their first. Most style guides quietly assume a native reader anyway, which means the actual audience and the assumed audience are two different groups, and the gap between them is where a surprising amount of avoidable confusion lives.
This isn’t an argument for dumbing anything down. A non-native reader is not a less capable reader — they are frequently reading in a professional capacity, at a high level of technical skill, in a language they had to learn deliberately rather than absorb as a child. The problem isn’t their ability. It’s that fluency in a second language is uneven in a specific, predictable way, and that unevenness lines up almost exactly with the parts of English native writers don’t notice because they never had to learn them explicitly.
Why idioms are invisible to the person who wrote them
A native English speaker learns “touch base” and “move the needle” the way they learn everything else as a child: by hearing it in context, dozens of times, until the meaning just arrives. Nobody sits down and explains that “touch base” has nothing to do with baseball. By the time that writer is producing documentation, the idiom has been fully absorbed — it doesn’t feel figurative anymore, it just feels like a normal way to say “check in.”
A reader who learned English as an adult, from textbooks and classes rather than childhood immersion, typically has the opposite experience: idioms were taught as a distinct, explicit category, precisely because they can’t be decoded from their individual words. That reader knows to be suspicious of a phrase that doesn’t parse literally. The native writer, who never had to develop that suspicion, doesn’t reliably notice when they’ve used one.
Phrasal verbs are a quieter version of the same gap
Idioms are the obvious case. Phrasal verbs are the one native writers almost never think to check, because they don’t read as figurative language at all — “set up,” “put off,” and “look into” feel like completely ordinary verbs, not a special category worth flagging. But their meaning is exactly as non-compositional as an idiom’s: nothing about “set” or “up” individually predicts that “set up the server” means “configure it.” A learner has to memorize each phrasal verb as its own unit, the same way they’d memorize an idiom, and English has hundreds of them in everyday technical use.
This is why a word like “configure,” despite being longer and more formally Latinate than “set up,” is often the easier word for a non-native reader. It’s transparent: many languages already have a close cognate for a word with Latin roots, and its meaning doesn’t depend on knowing an idiomatic convention specific to English. This runs backward from the usual plain-English advice to prefer short, common words over long, formal ones — and it’s the one place in this kind of checklist where that advice needs an explicit exception, because the usual advice optimizes for a native reader’s ear, not a learner’s parsing process.
Rare words are a matter of degree, not a bright line
Vocabulary difficulty isn’t binary. A word doesn’t sit in a “simple” or “hard” bucket — it sits at some rank in a rough ordering from words nearly every reader already knows to words only a specialist would recognize, and that ordering matters more than any single cutoff. A word ranked just outside the top thousand is a mild ask. A word ranked in the tens of thousands is a real one. Treating the whole category as one undifferentiated pile of “hard words” throws away the one piece of information that actually tells you how much it’s asking of the reader.
It also means a domain allowlist isn’t optional decoration on a vocabulary checker — it’s the thing that makes the distinction between “genuinely obscure” and “necessary technical term” possible at all. “Kubernetes” and “photosynthesis” are both statistically rare. Only one of them is jargon a particular audience needs to know, and no frequency list can tell the difference on its own; that judgment has to come from the person who knows their own readers.
What this changes in practice
None of this means avoiding every idiom, phrasal verb, or uncommon word — that would produce flat, evasive prose that serves nobody. It means treating vocabulary difficulty the way this site treats readability more generally: as something to notice and weigh deliberately, sentence by sentence, rather than either ignoring it entirely or chasing a single score. A phrasal verb in casual internal notes is fine. The same phrasal verb in a setup guide that half your users will read in their second language is worth a second look, and a five-second rewrite once you’ve noticed it.
Check your own writing
The plain language checker runs all of this automatically: rare vocabulary ranked against a frequency list built specifically for language learners, idioms with a literal paraphrase, phrasal verbs flagged only in their verb form (not their equally common noun form), and a domain allowlist so your own necessary jargon stops getting flagged the moment you add it.