---
title: Accessibility and inclusive writing
description: Guidelines for accessible, inclusive, and global-first content
---

Source: https://clickhouse.design/brand/guidelines/accessibility

# 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](/brand/guidelines/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](/docs/getting-started).

**❌ Don't:**
To learn more, [click here](/docs/getting-started).

### 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](https://hemingwayapp.com/)**: Highlights complex sentences and suggests simpler alternatives
- **[Grammarly](https://www.grammarly.com/)**: Reviews grammar, spelling, and clarity (note: English only, not always perfect)

Use these as guides, not gospel. Always review suggestions in context.