---
title: Writing for support and docs
description: Guidelines for documentation, tutorials, guides, and help content
---

Source: https://clickhouse.design/brand/guidelines/writing-for-support

# Writing for support and docs

Documentation helps users move fast. Be technical, be direct, respect their time. See [Voice and tone](/brand/guidelines/voice-and-tone) for the foundation.

For technical formatting rules (code blocks, links, tabs), see the [ClickHouse docs contributing guide](https://github.com/ClickHouse/clickhouse-docs/blob/main/contribute/contrib-writing-guide.md).

## General principles

1. **Stay on topic.** Don't stray from the title or topic at hand. Readers clicked through expecting specific answers.
2. **Be scannable.** Use short, descriptive headings. Organize content so readers can quickly find what they need.
3. **Keep it simple.** Target sentences under 25 words. Avoid gerunds and idioms that don't translate well.

## Documentation structure

### Page anatomy

A documentation page typically includes:

1. **Title**: Clear, descriptive, action-oriented when appropriate
2. **Introduction**: 1-2 sentences explaining what the page covers and who it's for
3. **Prerequisites** (if needed): What users need before starting
4. **Main content**: Organized with clear headings
5. **Next steps** (if applicable): Where to go from here

### Headings

Use headings to create a scannable structure. Headlines should be short, descriptive, and parallel in structure.

**✅ Do:**

- Installing ClickHouse
- Configuring your first table
- Running queries

**❌ Don't:**

- How to install ClickHouse on your machine
- Configuration
- Querying data from tables

## Tutorials and guides

### Step-by-step instructions

Number your steps. Start each step with an action verb. One action per step when possible.

**✅ Do:**

1. Open the ClickHouse Cloud console.
2. Click **Create service**.
3. Select your cloud provider and region.
4. Click **Create**.

**❌ Don't:**

1. First, you'll want to open the ClickHouse Cloud console, then find and click the Create service button.
2. Now you need to select your cloud provider, and also pick a region, before finally clicking Create.

### Screenshots and visuals

Use screenshots to support instructions, especially for complex UI interactions. Every screenshot should:

- Show exactly what the text describes
- Be cropped to focus on the relevant area
- Include alt text describing the image

### Code examples

Specify the language for syntax highlighting. Show realistic, runnable examples when possible.

**✅ Do:**

```sql
SELECT count() FROM system.tables
```

**❌ Don't:**

```
SELECT count() FROM system.tables
```

(Missing language specification)

## Help articles

Help articles should follow a problem-solution structure:

1. **Problem**: What issue is the user experiencing?
2. **Cause**: Why does this happen? (brief)
3. **Solution**: How to fix it (step by step)

**✅ Structure:**

**Title:** Connection timeout errors

**Problem:** You receive a timeout error when connecting to your ClickHouse Cloud service.

**Cause:** This typically happens when your IP address isn't in the service's allowlist.

**Solution:**

1. Open the ClickHouse Cloud console.
2. Navigate to your service's **Settings**.
3. Under **IP Access List**, click **Add IP**.
4. Enter your IP address and save.

## Release notes

Release notes inform users about changes. Be specific about what changed and why it matters.

### What to include

- New features and improvements
- Bug fixes that affect user experience
- Breaking changes (prominently flagged)
- Deprecations
- Migration steps when needed

**✅ Do:**
**New:** Added `async_insert_max_query_number` setting to control query batching in async inserts.

**Fixed:** Resolved an issue where queries with large JOIN operations could cause memory spikes.

**❌ Don't:**

- Various bug fixes and improvements
- Fixed stuff
- New features added

## API documentation

### Consistency

Use consistent patterns for documenting endpoints, parameters, and responses.

### Include examples

Show request and response examples for every endpoint. Use realistic data.

**✅ Structure:**

**Endpoint:** `POST /v1/organizations/{orgId}/services`

**Description:** Creates a new ClickHouse Cloud service.

**Parameters:**

| Name     | Type   | Required | Description                      |
| -------- | ------ | -------- | -------------------------------- |
| name     | string | Yes      | Service name                     |
| provider | string | Yes      | Cloud provider (aws, gcp, azure) |

**Example request:**

```json
{
  "name": "production-analytics",
  "provider": "aws",
  "region": "us-east-1"
}
```

## Tone in support content

Support content should be:

- **Direct**: Get to the point. Respect the reader's time.
- **Technical**: Speak to builders. Use precise language.
- **Helpful**: Focus on solving the problem.
- **Never condescending**: Don't say "simply" or "obviously."

**✅ Do:**
New to ClickHouse? Start with the Getting Started guide.

**❌ Don't:**
Obviously, you'll need to have ClickHouse installed first.

**❌ Don't:**
Simply run the following command...