Accessibility and inclusive writing
Accessible writing ensures everyone can understand and use our content. This supports our goal of being technical without being exclusionary. See Voice and tone for the foundation.
Plain language
Keep it simple
Use simple words and short sentences. Target sentences under 25 words. This helps:
- Non-native English speakers
- Readers using translation tools
- Neurodivergent readers
- Everyone scanning quickly
✅ Do: ClickHouse stores data in columns. This makes queries faster.
❌ Don’t: ClickHouse utilizes a columnar storage paradigm that facilitates accelerated query execution performance.
Avoid business jargon
Technical terms are fine—we speak to builders. Business jargon is not. Function over frills.
✅ Do:
- Use
- Start
- Help
- Show
❌ Don’t:
- Leverage
- Kickoff
- Facilitate
- Surface
Global-first writing
Write for a global audience. Our readers span many countries, cultures, and languages.
Avoid idioms and colloquialisms
Phrases like “hit the ground running” or “low-hanging fruit” don’t translate and confuse non-native speakers.
✅ Do:
- Start quickly
- Easy improvements
- Make progress
❌ Don’t:
- Hit the ground running
- Low-hanging fruit
- Move the needle
Consider cultural context
- Don’t assume familiarity with holidays, sports, or cultural references
- Use examples that work globally
- Avoid humor that relies on cultural knowledge
✅ Do: Schedule reports to run at the start of each month.
❌ Don’t: Schedule reports to run after the Super Bowl.
Inclusive language
Gender-neutral pronouns
Use “they/them/their” as singular pronouns when gender is unknown or irrelevant.
✅ Do: When a user creates a query, they can save it to their workspace.
❌ Don’t: When a user creates a query, he can save it to his workspace.
Avoid gendered terms
Use inclusive alternatives for gendered language.
✅ Do:
- Team, folks, everyone
- Sales representative
- Workforce, staff
- Artificial, synthetic
❌ Don’t:
- Guys (for mixed groups)
- Salesman
- Manpower
- Man-made
Avoid harmful terms
Some common tech and business phrases are culturally appropriative or insensitive.
| Avoid | Why | Use instead |
|---|---|---|
| sherpa | Refers to an ethnic group | guide, expert, mentor |
| open the kimono | Culturally appropriative | be transparent, share details |
| off the reservation | Culturally insensitive | unexpected, unconventional |
| master/slave | Harmful terminology | primary/replica, main/secondary |
| whitelist/blacklist | Racial connotations | allowlist/blocklist |
| sanity check | Ableist language | quick check, spot check |
| crazy, insane | Ableist language | surprising, unexpected |
Avoid tech clichés
Overused terms dilute meaning and can exclude people who don’t know the references.
❌ Avoid:
- Rockstar
- Ninja
- Wizard
- Guru
- 10x
✅ Use instead:
- Expert
- Specialist
- Experienced
- Skilled
Accessible content structure
Use proper headings
Headings create structure for screen readers. Never skip heading levels (e.g., jumping from H1 to H3).
✅ Do:
# Page title (H1)
## Section (H2)
### Subsection (H3)
## Another section (H2)❌ Don’t:
# Page title (H1)
### Subsection (H3) ← Skipped H2
## Section (H2)Write descriptive links
Link text should describe the destination. Never use “click here” or “read more” alone.
✅ Do: Learn more in our getting started guide.
❌ Don’t: To learn more, click here.
Use lists for multiple items
Lists are easier to scan than comma-separated items in a paragraph. They also help screen reader users understand the structure.
✅ Do: ClickHouse supports:
- MySQL
- PostgreSQL
- MongoDB
❌ Don’t: ClickHouse supports MySQL, PostgreSQL, and MongoDB.
Avoid directional language
Don’t refer to “the sidebar on the right” or “the button below.” Screen readers don’t convey visual position, and layouts change on mobile.
✅ Do: Select your region in the Region dropdown.
❌ Don’t: Select your region from the dropdown on the right.
Images and media
Alt text
Every image needs alt text describing what it shows. For charts and graphs, include the key data.
✅ Do:
alt="Bar chart showing query latency decreasing from 500ms to 50ms after optimization"
❌ Don’t:
alt="Chart"
alt="image"
alt="" (for non-decorative images)
Video captions
All videos should have closed captions or transcripts. This helps:
- Deaf or hard-of-hearing viewers
- People in sound-sensitive environments
- Non-native speakers
- Anyone who prefers reading
Writing tools
These tools can help improve accessibility and clarity:
- Hemingway Editor: Highlights complex sentences and suggests simpler alternatives
- Grammarly: Reviews grammar, spelling, and clarity (note: English only, not always perfect)
Use these as guides, not gospel. Always review suggestions in context.