# ClickHouse Content & Writing Guidelines > Knowledge file for the ClickHouse design agent. > Canonical source: https://clickhouse.design/brand/guidelines/voice-and-tone > Compiled from the Content guidelines (voice & tone, grammar & mechanics, product, marketing, support/docs, accessibility). Source of truth for voice, tone, grammar, and mechanics — cite directly; don't say "no ruling" when a rule appears here. --- ## Voice and tone **Voice** is who we are (constant). **Tone** adapts to context. Built for engineers, trusted by leaders — elite tech, street-smart attitude. Never condescend; prove value in milliseconds. **Personality:** raw, confident, engineered for performance. Sharp, efficient, sometimes blunt, never dull. Defined by speed, intelligence, edge. **Values:** speed is everything · function over frills · always technical, never generic · build with pride, not permission · say what you mean, prove it. **Principles:** - **Be direct** — cut filler. ✅ "ClickHouse processes 1B rows in under a second." ❌ "We're excited to share that ClickHouse can potentially process up to 1B rows…" - **Technical, not generic** — precise, no "cutting-edge next-generation solution." - **Prove it** — numbers, benchmarks, examples; not "incredibly fast." - **Keep it simple** — present tense, active voice, short sentences. - **Global audience** — gender-neutral they/them; no idioms that don't translate. **Tone by context:** Announcements → confident, not hype. Errors → direct + helpful, never blame, no "oops." Technical → lead with what matters, precise not exhaustive. **Words to avoid → use instead:** leverage/utilize/facilitate → use, help · cutting-edge/next-generation → be specific · rockstar/ninja/wizard/guru/10x → expert, specialist · synergy/paradigm shift → say what you mean · sherpa → guide · master/slave → primary/replica. --- ## Grammar and mechanics - **Capitalization** — sentence case for titles, headings, buttons, menu items (only first word + proper nouns). ✅ "A brand new release from ClickHouse." Don't capitalize after a colon in running text (do in titles). - **Oxford comma — always use it.** ✅ "Morocco, Spain, and Portugal." - **e.g. / i.e.** — lowercase, no comma after. ✅ `e.g. Int32` ❌ `e.g., Int32` - **Periods** — one space after, not two. - **Apostrophes** — no apostrophe for plurals/acronyms (`APIs`, `URLs`, `OLAPs`); apostrophe only for possession. - **Ampersands** — don't use in official copy; spell out "and." - **Numbers/currency** — `$100M`, `$4K` (not `$100 MM`); Western format `1,000,000.00`; round for readability (`1.3B rows`). - **Dates/times** — `Apr 20, 2024`, lowercase `2:00 p.m.`; omit year if current year; double space between date and time (`Apr 20, 2024 2:16 p.m.`). - **Lists** — full sentences get capitals + end punctuation; fragments don't; never mix within a list. - **Standardized terms** — ClickHouse (not Clickhouse/Click House) · ClickHouse Cloud service (lowercase "service") · dataset (not data set) · United States · United Kingdom. - **Formatting** — **bold** for UI elements: "Click the **Start** button." Instructions: [noun] + [action] + [direction]. --- ## Writing for product (UI copy) Direct, specific, brief. - **Buttons** — action verbs naming what happens (Create service, Export as CSV), not OK/Confirm/Submit; for destructive actions name the target (`Delete "my-service"`). - **Errors** — what happened + what to do. No blame, no "oops," no raw codes without explanation. - **Empty states** — say why it's empty and the next action. - **Tooltips** — one sentence; add context, don't repeat the label. - **Confirmation dialogs** — title is a question naming action + target; specific verbs; 1–2 sentence consequence. - **Loading/success** — be specific ("Creating service…", "Service created"), not "Loading…"/"Success!". --- ## Writing for marketing Confident, technical, direct — prove value, no fluff. **US English** in official communications (an attributed blog author may use their own English). - **Headlines** — lead with value, be specific, prove with numbers. - **Features** — what it does and why it matters; technical over generic. - **Landing pages** — Hero → Problem → Solution → Proof → CTA. - **Blogs** — for developers/engineers/leaders; explain then link to deep dives; define jargon on first use. - **Email** — clear non-clickbait subject; one message/action; short paragraphs. - **Social** — short, correct grammar, sparing hashtags; no "like/RT for reach"; pause scheduled posts during major news. - **Case studies** — customer's own voice + specific numbers; context → challenge → solution → results → quote. - **Press releases** — formal: full intro, "ClickHouse, Inc.", boilerplate + contact, AP style; involve comms. --- ## Writing for support and docs Technical, direct, time-respecting. Sentences under 25 words. - **Structure** — title → 1–2 sentence intro → prerequisites → content with clear headings → next steps. - **Headings** — short, descriptive, parallel ("Installing ClickHouse", "Running queries"). - **Steps** — numbered, one action each, starting with a verb. - **Code** — always specify the language; realistic, runnable examples. - **Help articles** — problem → cause (brief) → solution. - **Release notes** — specific (New / Fixed / Breaking / Deprecated), not "various fixes." - **Tone** — helpful, never condescending; avoid "simply"/"obviously." --- ## Accessibility and inclusive writing - **Plain language** — simple words, short sentences; helps non-native speakers, translation tools, neurodivergent readers. - **Avoid jargon & idioms** — no "leverage/kickoff/surface", no "hit the ground running/low-hanging fruit/move the needle"; no culture-specific references. - **Inclusive** — they/them; team/folks (not "guys"), sales representative, workforce. - **Harmful terms → use instead:** sherpa → guide · master/slave → primary/replica · whitelist/blacklist → allowlist/blocklist · sanity check → quick check · crazy/insane → surprising · open the kimono → be transparent. - **Structure** — don't skip heading levels; descriptive link text (not "click here"); use lists; no directional language ("the button below"); name the element. - **Media** — descriptive alt text (key data for charts); captions/transcripts for video.