Accessibility and inclusivity for developer docs
Zapier developer documentation is read by engineers, partners, and technical users in 100+ countries. Many are non-native English speakers, some use assistive technologies, and increasingly the reader is a coding agent. Writing accessibly and inclusively serves all of them at once. This skill is the authoritative source for sensory-neutral language and accessibility in this repo. Pair it with writing-standards-dev-docs (which references it) and formatting-guidelines (components, alt text syntax).When to use
- Writing or editing any page in this repo
- Reviewing a draft for accessible, inclusive language
- Adding images, diagrams, code blocks, or links
Sensory-neutral language
Do not assume the reader can see, hear, or interact in a specific way. Sensory-specific language excludes people who use assistive technologies and is less precise for everyone.| Instead of | Use |
|---|---|
| See | Check, review, go to, refer to, find |
| Look at / Look for | Check, examine / Find, locate |
| View | Check, open, review |
| Watch | Follow, track, monitor |
| Walk through / Walk you through | Go through, complete / Guide you through, explain |
| As you can see | Notice that, the output shows |
| The following screenshot shows | The following example shows |
| Above / Below (alone) | Pair with a name: “in the Authentication section”, “in the example that follows” |
Images and diagrams
- Write meaningful alt text. Convey the information or function the image carries, not “screenshot of X”. For a decorative image that adds no information, use empty alt text so screen readers skip it.
- Do not put information only in an image. Anything required to complete a task — a setting, a value, an endpoint — must also appear in text. A reader using a screen reader, or an agent parsing the page, cannot extract it from a picture.
- Describe diagrams in text. For an architecture or flow diagram, summarize the flow in a sentence or list so the meaning survives without the image.
Headings and structure
- Use a correct heading hierarchy (H1 → H2 → H3) with no skipped levels. Screen reader users navigate by headings.
- Keep nesting shallow — three levels or fewer. Deeper nesting is hard to navigate.
- Front-load the point of each section in its first sentence so readers scanning by heading get the answer fast.
Link text
Link text must describe its destination on its own, because assistive tech can list links out of context.- Avoid “click here”, “read more”, “this page”.
- Write “Set up authentication” or “the Trigger Inbox API reference”, not “click [here]”.
Accessible code blocks
- Introduce every code block in text. State what it does before it appears, since a code block alone can be opaque to a screen reader or an agent.
- Use a language tag on each fenced block so it is announced and highlighted correctly.
- Do not rely on color or formatting alone to convey meaning (for example, “the red value”). Name the line, field, or token.
- Keep comments meaningful. In-code comments are read aloud — use them to explain intent, and follow the placeholder rules in code-examples for fake values.
Plain language for cognitive accessibility
Clear writing helps every reader and is essential for people with reading or cognitive disabilities. This overlaps with writing-standards-dev-docs — apply both.- One idea per sentence; short paragraphs with the key point first.
- Active voice and present tense.
- Be literal — avoid idioms, slang, sarcasm, and cultural references that confuse non-native readers (“hang in there”, “out of the box”, “piece of cake”).
- Avoid noun stacks of more than three words.
- Use consistent terminology — one term per concept (see glossary-terminology).
- Avoid ALL CAPS for emphasis; it is harder to read and reads as shouting.
Inclusive terminology
Avoid ableist, gendered, or biased language. This includes common technical terms with non-inclusive origins.| Instead of | Use |
|---|---|
| Whitelist / Blacklist | Allowlist / Denylist |
| Master / Slave | Primary / Replica, Main / Secondary |
| Master branch | Main branch |
| Sanity check | Quick check, confidence check |
| Dummy value | Placeholder value, sample value |
| Kill / Hang (a process) | Stop, end / Stops responding |
| Grandfathered | Legacy |
| He / She (unknown reader) | They / their |
| Guys | Everyone, folks, the team |
| Crazy, insane (as emphasis) | Drop it, or use “unexpected”, “surprising” |
Quick-check list
Before finalizing any page, confirm:- No sensory language (see, view, look at, watch, walk through, “as you can see”)
- Directional cues are paired with a named element or section
- The page is fully understandable with images turned off — read it ignoring every image and confirm no step or value is lost (this is also how a screen reader and an agent receive it)
- All images have meaningful alt text; no required information lives only in an image
- Diagrams are summarized in text
- Heading hierarchy is correct and no deeper than three levels
- Link text describes its destination (no “click here”)
- Code blocks are introduced in text and tagged with a language
- Inclusive terminology (allowlist/denylist, main/replica, they)
- No idioms, slang, or ALL CAPS emphasis
Related skills
- writing-standards-dev-docs — voice, sentence case, contractions, em-dashes, active voice, steps
- formatting-guidelines — image, alt-text, and component syntax
- code-examples — runnable examples and placeholder values
- glossary-terminology — one term per concept