Grammar and mechanics
Consistent formatting makes content easier to scan and trust. For voice and personality, see 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.
❌ Don’t:
- April 20th 2024
- 20th April, 2024
- 2:00PM / 2:00 PM / 2:00pm
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.