Writing for support and docs

Documentation helps users move fast. Be technical, be direct, respect their time. See Voice and tone for the foundation.

For technical formatting rules (code blocks, links, tabs), see the ClickHouse docs contributing guide.

General principles

Stay on topic. Don’t stray from the title or topic at hand. Readers clicked through expecting specific answers.
Be scannable. Use short, descriptive headings. Organize content so readers can quickly find what they need.
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:

Title: Clear, descriptive, action-oriented when appropriate
Introduction: 1-2 sentences explaining what the page covers and who it’s for
Prerequisites (if needed): What users need before starting
Main content: Organized with clear headings
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:

Open the ClickHouse Cloud console.
Click Create service.
Select your cloud provider and region.
Click Create.

❌ Don’t:

First, you’ll want to open the ClickHouse Cloud console, then find and click the Create service button.
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:

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:

Problem: What issue is the user experiencing?
Cause: Why does this happen? (brief)
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:

Open the ClickHouse Cloud console.
Navigate to your service’s Settings.
Under IP Access List, click Add IP.
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:

{
  "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…

Marketing Grammar and mechanics