My dad said my site read like a second language
I showed my dad this site. He is a capable man who has used computers for decades. He read for a while, and then he said it was like reading a second language he knew a few words of. He could tell it was about something. He could not tell what he was supposed to do.
My first instinct was that this was a design problem. The site is dark, the type is not large, there is movement. Obviously, I thought, I should make a calmer version with bigger text and more contrast. That is what accessibility means.
I was wrong, and I only found out because I built the calm version and he still could not read it.
Handing someone a brighter lamp does not help if the book is in a language they do not speak. The lighting was never the thing.
The barrier was the words. Not long words, and not technical terms I had defined. It was the unmarked ones, the vocabulary that had become invisible to me because I use it daily. Container. Reverse proxy. Bind to an interface. Headless. I was not showing off. I genuinely did not see them any more, which is exactly why they were doing so much damage.
So the plain edition became a rewrite rather than a restyle. Same truths, same steps, different vocabulary. The rule I settled on, after getting it wrong in both directions, is this: simplify the language, never the truth. Easy writing is not writing that says less. It is writing that makes the same claim without requiring you to already know.
Getting the voice right took longer than the design. The failure mode on one side is jargon. On the other side is condescension, which is worse, because a reader can look up a word but cannot recover from being patronised. Warm, patient, curious, never talking down. Assume intelligence, assume no shared vocabulary. Those are compatible, and holding both is the actual skill.
The design work still mattered, and I kept all of it. It just turned out to be the second thing. Contrast and type size make a readable page readable. They cannot make an unintelligible page intelligible, and I had been solving the wrong problem confidently.
How to build an accessible parallel edition: finding the words that are actually blocking people, the voice rules, the contrast and type targets, a text size control, and the pattern for defining a term without interrupting the sentence.
1. Find the blocking words by watching someone read, not by guessing
You cannot audit your own vocabulary, because the invisible words are invisible to you. Sit with one person who is not in your field and ask them to say when they stop understanding.
# jargon.md, built from what they actually stumbled on
# container -> "a packaged app that runs in its own sealed box"
# bind to -> "which network connections it will answer"
# headless -> "no screen attached, you use it over the network"
# reverse proxy -> "a front desk that passes requests to the right room"Ask them to read aloud. The pause before a word is the data, and it happens before they consciously decide they are confused.
2. Rewrite, do not restyle, and keep every claim
Go paragraph by paragraph. The test for each is whether the same thing is still true, not whether it is shorter.
# the rule
# SIMPLIFY the language. NEVER simplify the truth.
# so this is wrong, because it removes the warning:
# "bind the service to loopback" -> "make the service private"
# and this is right, because the caution survives:
# -> "tell the service to answer only this computer, so other devices
# on your network cannot reach it"3. Write the voice rules down and check against them
Four lines on the wall. They catch both failure modes.
# voice.md
# warm : a person talking to a person
# patient : explain the thing rather than linking away from it
# intriguing: say why it is worth doing before how
# never condescending: no "simply", no "just", no "obviously",
# no "don't worry about why"That last list is the most useful part. Those four words are where condescension actually enters the text, and they are easy to grep for.
4. Set the contrast and type targets, then measure them
Pick the strict target. Measuring matters more than choosing, because a value you assumed is not a value you have.
# targets
# contrast : 7:1 for body text (the strict level), measured not estimated
# body : 18px minimum, and larger line height than you think
# measure : 60 to 75 characters per line, no wider
# ground : light background, dark textMeasure the computed colours on the rendered page rather than reading your own stylesheet, because inheritance and opacity will surprise you. Walk the real text nodes, compute the ratio against the effective background, and report the worst one you find.
5. Give the reader a text size control, and remember it
Browser zoom exists, but a visible control on the page tells the reader they are allowed to change things, and that message is worth as much as the feature.
# scale with one variable, so one control moves everything together
# :root { --text-scale: 1; }
# body { font-size: calc(18px * var(--text-scale)); }
# three buttons, and store the choice so it survives navigation
# wrap storage access in a try/catch: it throws in private windows
# and the page must still work when it fails6. Define a term without breaking the sentence
Stopping to define things ruins the flow, and a glossary nobody opens is decoration. Put the short meaning inline at first use, in the prose itself.
# inline, parenthetical, once, at first use on that page
# "...runs in a container (a packaged app in its own sealed box,
# so it cannot disturb the rest of the machine)..."
# then use the plain phrase for the rest of the page, not the term7. Be honest about what is not translated yet
A parallel edition grows one page at a time, and pretending otherwise is the one thing guaranteed to lose a reader's trust. Label it and link to the original.
# for a page not yet rewritten, do NOT hide the link
# show it, label it "not in plain English yet, this goes to the
# original version", and let the reader decide
# and publish the real count: "N of M pages", where M is every page
# and not just the ones you finishedThe honest catch: one reader found my blind spots, and one reader has blind spots of their own. This edition is tuned to the words that stopped one capable person. The next reader will stop somewhere I have not thought about, and the only way to find that is to keep watching people read.
Related: what I learned the hard way is the same instinct about writing things down before you forget why.