My dad said my site read like a second language
What you will learn
- Why a brighter, calmer page did not help, and what the real barrier was
- The rule that separates easy writing from writing that says less
- How to find the words that are blocking people, which you cannot do by guessing
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 being accessible means.
I was wrong, and I only found out because I built the calm version and he still could not read it.
Handing somebody 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 already explained. 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 this edition became a rewrite rather than a restyle. Same truths, same steps, different vocabulary.
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 on one side is jargon. On the other side is talking down to people, which is worse, because a reader can look up a word but cannot recover from being patronised.
Warm, patient, curious, never condescending. Assume intelligence, assume no shared vocabulary. Those two are compatible, and holding both at once is the actual skill.
The design work still mattered. It was just second
I kept all of it. 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.
Simplify the language, never the truth.
How to build a parallel edition like this one: finding the words that are actually blocking people, the voice rules, the contrast and type targets, a text size control, and how to explain a term without interrupting the sentence.
1. Find the blocking words by watching somebody read
What this does: gets you a real list, from a real reader, of the words that stop them.
Why you cannot do this alone: you cannot audit your own vocabulary, because the invisible words are invisible to you.
Ask them to read aloud. The pause before a word is the data, and it happens before they consciously decide they are confused.
# 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"2. Rewrite, do not restyle, and keep every claim
What this does: goes paragraph by paragraph, checking that the same thing is still true rather than that it is shorter.
The test for each paragraph: is the claim intact? If a warning disappeared, you simplified the truth rather than the language.
# the rule
# SIMPLIFY the language. NEVER simplify the truth.
# wrong, because the warning is gone:
# "bind the service to loopback" -> "make the service private"
# right, because the caution survives:
# -> "tell it to answer only this computer, so other devices on your
# network cannot reach it"3. Write the voice rules down and check against them
What this does: puts four lines on the wall that catch both failure modes.
Which part is most useful: the last list. Those four words are where condescension actually enters the text, and they are easy to search for.
# 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"4. Set the contrast and type targets, then measure them
What this does: picks the strict targets and then checks the finished page against them.
Why measuring matters more than choosing: a value you assumed is not a value you have.
Measure the finished page, not your stylesheet. Inheritance and transparency will surprise you. Walk the real text, work out the ratio against the background that is really behind it, and report the worst one you find.
# targets
# contrast : 7 to 1 for body text, the strict level, measured not estimated
# body : 18px minimum, and more line spacing than you think
# measure : 60 to 75 characters per line, no wider
# ground : light background, dark text5. Give the reader a text size control, and remember their choice
What this does: scales everything from one value, so three buttons move the whole page together.
Why bother when browser zoom exists: a visible control tells the reader they are allowed to change things, and that message is worth as much as the feature.
Handle storage failing. Saving the choice throws an error in private windows, so wrap it and make sure the page still works when it fails.
# scale from one value
:root { --text-scale: 1; }
body { font-size: calc(18px * var(--text-scale)); }6. Explain a term without breaking the sentence
What this does: puts the short meaning inline at first use, in the prose itself.
Why not a glossary: stopping to define things ruins the flow, and a glossary nobody opens is decoration.
Then use the plain phrase for the rest of the page, rather than the term.
# inline, in brackets, 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)..."7. Be honest about what is not translated yet
What this does: shows the link to a page that has not been rewritten, labels it clearly, and lets the reader decide.
Why not hide it: a parallel edition grows one page at a time, and pretending otherwise is the one thing guaranteed to lose a reader's trust.
And publish the real count, out of every page, not just the ones you finished.
# 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 chooseOne 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 reading: the things I got wrong so you do not have to is the same instinct about writing things down before you forget why.
This page in the original Kyber Cypher voice: My dad said my site read like a second language