---
title: Grammar and mechanics
description: Punctuation, capitalization, and formatting standards for ClickHouse content
---

Source: https://clickhouse.design/brand/guidelines/grammar-and-mechanics

# Grammar and mechanics

Consistent formatting makes content easier to scan and trust. For voice and personality, see [Voice and tone](/brand/guidelines/voice-and-tone).

## Capitalization

### Sentence case for titles and headings

Capitalize only the first word and proper nouns. This applies to page titles, section headings, button labels, and menu items.

**✅ Do:**
A brand new release from ClickHouse

**❌ Don't:**
A Brand New Release from ClickHouse

### After colons

Don't capitalize after a colon in running text. Do capitalize in titles.

**✅ Do:**
There's one catch: the data must be sorted first.

**✅ Do (title):**
ClickHouse Newsletter 2024: There's a new window function for that!

## Punctuation

### Oxford comma

Always use the Oxford comma (the comma before "and" in a list of three or more items).

**✅ Do:**
During our vacation, we visited Morocco, Spain, and Portugal.

**❌ Don't:**
During our vacation, we visited Morocco, Spain and Portugal.

### Abbreviations: e.g. and i.e.

Use lowercase. Don't add a comma after.

**✅ Do:**
Use a numeric type (e.g. Int32 or Float64) for this column.

**❌ Don't:**
Use a numeric type (e.g., Int32 or Float64) for this column.

**❌ Don't:**
Use a numeric type (E.g. Int32 or Float64) for this column.

### Spaces after periods

Use one space after periods, not two. The two-space convention was for typewriters and doesn't translate well to digital type.

### Apostrophes

Plural words don't use apostrophes. Most acronyms follow this rule.

**✅ Do:**

- OLAPs (multiple OLAP platforms)
- APIs
- URLs

**❌ Don't:**

- OLAP's
- API's
- URL's

**Exception (possession):**

- The ClickHouse OLAP's performance

### Ampersands

Don't use ampersands in official communications. Spell out "and" for consistency.

**✅ Do:**
Logs, events, and traces

**❌ Don't:**
Logs, events, & traces

## Numbers and currency

### Currency formatting

Use letter abbreviations for large numbers. Use Western number format.

**✅ Do:**

- $100M (not $100 MM)
- $4K
- $40K
- $400K

**Number format:**

- 1,000,000.00 (Western format)

### Rounding for readability

Round large numbers to make them more readable. Users don't need exact figures in most contexts.

**✅ Do:**
1.3B rows

**❌ Don't:**
1,349,304,201 rows

## Dates and times

Use three-letter month abbreviations with the day and four-digit year. For times, use lowercase a.m./p.m. with a space.

**✅ Do:**

- Apr 20, 2024
- Sat, Apr 20, 2024
- 2:00 p.m.
- Apr 20, 2024, 2:00 p.m.

**❌ Don't:**

- April 20th 2024
- 20th April, 2024
- 2:00PM / 2:00 PM / 2:00pm

For dates that are in the context of the current year, don't include the current year.

Assume the current date is April 20, 2024

**✅ Do:**

- Apr 20

**❌ Don't:**

- Apr 20, 2024

For dates that require times, use double spaces between the date and the time

**✅ Do:**

- Apr 20  2:16:38 p.m.
- Apr 20, 2024  2:16:38 p.m.
- Sat, Apr 20, 2024  2:16:38 p.m.

**❌ Don't:**

- Apr 20, 2024, 2:16:38 p.m.
- Apr 20, 2024 - 2:16:38 p.m.
- Sat, Apr 20, 2024 | 2:16:38 p.m.

For Dates that require second precision, use second precision

**✅ Do:**

- Apr 20  2:16:38 p.m.
- Apr 20, 2024  2:16:38 p.m.
- Sat, Apr 20, 2024  2:16:38 p.m.

## Bulleted lists

### Punctuation

- If list items are complete sentences, use capital letters and end punctuation.
- If list items are fragments, no end punctuation is needed.
- Be consistent within a list—don't mix sentences and fragments.

**✅ Do (sentences):**

- ClickHouse stores data in columns.
- Queries run faster because only relevant columns are read.
- Compression is more effective with similar data grouped together.

**✅ Do (fragments):**

- Column-oriented storage
- Vectorized query execution
- High compression ratios

**❌ Don't (mixed):**

- Column-oriented storage
- Queries run faster because only relevant columns are read.
- High compression

## Standardized terms

| Use this                 | Not this                            |
| ------------------------ | ----------------------------------- |
| ClickHouse               | Clickhouse, clickhouse, Click House |
| ClickHouse Cloud service | ClickHouse Cloud Service            |
| dataset                  | data set                            |
| United States            | US, U.S.A., USA                     |
| United Kingdom           | UK                                  |

## Writing directions

Structure instructions clearly: \[Noun] + \[action] + \[direction].

**✅ Do:**
Insert the data into the table.

**✅ Do:**
Go to the developer portal and insert the sample dataset.

For deadlines and expectations: \[action] + \[ask] + \[date].

**✅ Do:**
Complete the migration by Friday.

## Formatting in instructions

Use **bold** for buttons, checkboxes, menu items, and other UI elements.

**✅ Do:**
Click the **Start** button.

**❌ Don't:**
Click the Start button.