Accessibility in Writing: How to Create Accessible Documentation That Works for Everyone

It started with a simple door. For a long time, the only way into the building was to pull the door open. That worked for most people, but not for everyone, so someone added an automatic door button. Then something interesting happened: parents with strollers started using it, along with people carrying coffee or laptops, and delivery workers with loaded carts. On busy days, almost everyone did. This is what is called the curb-cut effect. When you design something for people with disabilities, you usually make life easier for everyone else too. The same thing happens with documentation. Clear alt text, real headings, meaningful link text, and readable contrast all help people who use assistive technology, and they also make your docs easier for anyone to scan, search, and understand. The curb-cut effect — a feature built for one group ends up helping many This article walks through practical ways to make your documentation more accessible and why each one helps a wider audience than you might expect. What "accessible" means in documentation When I say accessible documentation, I mean documentation that anyone can read and understand, including people with disabilities. One thing people often miss is that disabilities aren’t always visible or permanent. It can be temporary, like a broken wrist that makes using a mouse painful for a few weeks. Or situational, like squinting at your phone in bright sunlight, where a low-contrast screen becomes unreadable. Disability can be permanent, temporary, or situational, shown as a blind developer using a screen reader, a person with a broken wrist relying on the keyboard, and someone reading a phone in bright sunlight. Personally, I’ve hit all three. A wrist injury once made scrolling painful; I've had to give up on docs I was reading outside because I couldn't make out the grey-on-white text. So when I write with accessibility in mind, I'm picturing real people: the developer using a screen reader on my API docs, the manager squinting at a diagram projected in a bright conference room, the new hire on a bus with a bad connection where images never load and only the alt text comes through. Writing alt text that carries meaning Alternative text, or alt text, is the short description you attach to an image. It stands in for the image when someone can't see it. Screen readers read it aloud, which is how blind or low-vision readers understand what your image shows. Search engines also read it, so adding good alt text also helps people find your content. And when an image fails to load on a slow connection, the alt text is all that survives. That's the permanent, the situational, and the everyday cases covered by one small attribute. Most alt texts are either missing or unhelpful. A few habits separate the good ones from the forgettable. Describe the role, not just the pixels. Think about why the image is in your document. If you're writing about team collaboration and you have a photo of two people laughing at a whiteboard, "Two people at a whiteboard" is accurate but pointless. "Two colleagues brainstorming together during a team session" tells the reader why the image is there. When writing alt text, the emotion and the purpose matter. Keep it to a sentence or two. You're giving the reader the main idea, not writing a paragraph. Using long descriptions interrupts the flow for screen-reader users. Drop the "Image of" prefix, too, since screen readers already announce that it's an image, and finish with a period so the reader hears a natural pause before the next line. Use empty alt text when the image adds nothing. If an image is purely decorative or the surrounding text already explains it, set alt="". The screen readers will skip it, which is exactly what you want. Leave the attribute in place, though, since removing it entirely can cause the file name to be read out instead. Give complex images a longer description elsewhere. A flowchart or architecture diagram won't fit in a sentence. Write short alt text for the gist, then put the full description in the body text or a linked page, and mention in the alt text where to find it, for example: "System architecture overview with three service layers. Full description follows below." Structure with real headings Headings are the backbone of navigable docs, and they're easy to get wrong. Screen-reader users often pull up a list of a page's headings and jump straight to the section they need, the same way a sighted reader skims. That only works if your headings are real headings. Bolding a line of text does nothing for that list because the screen reader sees an ordinary paragraph. Use actual heading levels and nest them in order without skipping, so an H2 is followed by H3s beneath it rather than jumping to H4. A logical heading outline helps everyone: it powers your table of contents, your in-page search, and the reader who's scanning for a specific answer. Check your colour contrast Low contrast is mildly annoying for most people and completely excluding for some. Having light grey text on white, or a thin font on pale blue, is hard for anyone to read on a screen in bright light, which is the situational case again. For a reader with low vision, the text can be impossible to read. The WCAG 2.1 contrast guidelines (Success Criterion 1.4.3) ask for a ratio of at least 4.5:1 for normal body text. Treat that as your guideline. You can use a free contrast checker that will tell you your ratio in seconds, so there's no reason to guess. Same letter A , different pairings — contrast is what decides whether you can read it, not the colour itself. Don't rely on colour alone Imagine a best-practices guide that uses green for the recommended approach and red for what to avoid. It looks clean, and you assume everyone reads it the way you do. But red-green colour blindness is quite common, affecting roughly 1 in 12 men and 1 in 200 women, and to those readers, the two colours can look nearly identical. The fix is simple: never let colour be the only signal in documentation. Pair a green thumbs-up with the word "Recommended" and a red thumbs-down with "Not recommended", and everyone gets the message regardless of how they perceive colour. The same rule applies to charts, status indicators, and error states. Whenever colour carries meaning, back it up with a label, a symbol, or a pattern. Colour, symbol, and label together. The green thumbs-up and red thumbs-down still read as "Recommended" and "Not Recommended" even for someone who can't tell the two colours apart. Write link text that stands on its own People who use screen readers often tab through a page's links out of context, relying solely on the link text used to decide where to go. On a page full of generic links, that sounds like: "Click here. Click here. Learn more. Learn more. This document." There's no way to tell any of them apart. Using descriptive link text fixes this instantly. For example, "Learn how to format accessible tables" and "Review the WCAG 2.1 colour contrast requirements" each say exactly where they lead, with no surrounding sentence required. As a bonus, search engines also weigh link text, so this helps people find your pages in the first place. Choose respectful language This last one isn't about markup language. When you write about disability, your word choices carry a message even when you don't intend one. Avoid calling people without disabilities "normal" or "healthy," which implies everyone else is abnormal or unwell. Use neutral, accurate terms such as nondisabled, sighted, hearing, or neurotypical to do the job. Skip framing that adds tragedy, too: "victim of," "suffering from," and "wheelchair-bound" all turn a fact into a misfortune. A person who uses a wheelchair isn't bound to it. Terms like "experiencing," "living with," and "uses a wheelchair" keep the person in charge of their own story. Using both person-first language ("people with disabilities") and identity-first language ("disabled people") is valid, and the right choice depends on what a person or community prefers. Either way, put the person first and avoid reducing anyone to a label like "the disabled." Make it a quick habit Accessibility is really just a facet of good writing. If you already care about clear structure, exact language, and helpful formatting, you're most of the way there. You don't need a formal audit, just a short gut-check while you edit. Check for things like: Are my headings real, nested heading levels, or did I only bold some text? Does every meaningful image have alt text that describes its purpose, and is decorative imagery marked as empty? Would my links make sense if read on their own, or out of context? Is my contrast high enough for someone reading on a phone in the sun? Am I using colour as the only way to signal something important? Run through that a few times, and it becomes second nature. Write with everyone in mind Accessible documentation is simply writing that works for everyone who reaches it. Every real heading, every purposeful line of alt text, every link that names its destination, and every readable colour choice helps someone, whether they're using a screen reader, searching on Google, or reading on a bright bus window. The permanent, temporary, and situational cases all converge on the same set of habits. Write for that reader too. They're already out there. I'll leave you with a line from accessibility expert Léonie Watson that has stuck with me: A good alt text can conjure up wonderfully stimulating mental images. -Leonie Watson References Léonie Watson quote: "Text descriptions and emotion-rich images," Tink (tink.uk). Contrast guidance: WCAG 2.1, Understanding Success Criterion 1.4.3: Contrast (Minimum), W3C. Google’s Technical writing for accessibility course. Colour-blindness statistics: Colour Blind Awareness.