Skip to main content

Snowplow documentation style guide

Grammar and spelling​

  • Use US spelling: "behavioral", "center", "organize", "modeled".
  • Treat "data" as singular: "the data is captured".
  • "Set up" is a verb. "Setup" is a noun or adjective. Never use "set-up".
  • "Log in" is a verb. "Login" is a noun or adjective. Never use "log-in".
  • Prefer "configuration" over "setup".
  • Prefer "credentials" over "login".
  • Spell out single-digit numbers as words: "three events" not "3 events".

Formatting and punctuation​

  • Use straight double quotes ("). Never use single quotes (') or smart quotes (”).
  • Use the Oxford comma: "events, entities, and schemas".
  • Use "and", never "&".

Headings​

  • Use only H2, H3, and rarely H4. Never use smaller headings.
  • H2 is for main sections. H3 is for subsections.
  • Never end headings with punctuation.
  • Use sentence case: "Configure how events are sent".
  • Prefer imperative voice: "Initialize the tracker" not "Tracker initialization".

Bold, italic, and code​

  • Use bold for UI elements: buttons, page titles, tabs, menus.
  • Use bold or italic to highlight key phrases. Never combine both on the same text.
  • Never bold entire paragraphs.
  • Use backticks for table names, field names, column names, class names, file names, and code references.
  • If the name has underscores, use code formatting.

Lists​

  • Introduce lists with a sentence ending in a colon.
  • Capitalize the first word of each item.
  • After a colon within a list item, continue lowercase: "Boolean: the value will be etc."
  • No period at the end unless the item contains multiple sentences.

Tables​

  • Capitalize the first word of cell text.
  • Exception: code should use appropriate case (e.g., true).
  • Never use bold for column headings.

Page structure​

  • Precede every heading and list with at least one paragraph of prose.
  • Never use page dividers (---).
  • Never use ellipses (...).

Content types and page templates​

Every page sets content_type in its frontmatter. Use the template for that type. Each template stays within 3 to 5 H2 sections. Put the description and when or why to use the feature in the opening paragraphs, before the first H2. Never add a "Next steps" H2: end the page with a short paragraph of links instead.

  • concept: explains what something is and why it matters. H2s: What it is and why it matters, How it works (a diagram plus the same steps in text), Example, Related concepts.
  • how-to: one task, done in order. H2s: Before you begin, Steps (in <Steps>, with verification as the last step), Troubleshooting (exact error string, then the fix). Omit Troubleshooting when there are no known errors. Never write generic troubleshooting advice.
  • tutorial: a guided, end-to-end example that builds something. H2s: What you'll build (with a time estimate, "less than 10 minutes"), Requirements, Steps (in <Steps>), Clean up.
  • reference: lookup material. H2s: Parameters (a <ParamTable> or a generated table), Example, Errors, Version applicability (with <AppliesTo>). Omit Errors or Version applicability only when there's nothing to list.
  • integration: a destination or third-party connection. Start with <IntegrationBadges id>. H2s: Compatibility, Connect, Configure (generated by EventForwardingSchemaTable where it applies), Troubleshooting.
  • sdk: a tracker or SDK landing page. H2s: Feature support (the row from the tracker matrix), Install and initialize, Track your first event. Show the support tier with <TrackerTier id> and the feature support row with <TrackerFeatures id>.
  • landing: a hub or overview that routes readers to other pages. Use a task table ("I want to", "Go to") and short grouped link lists. Never put the only copy of a procedure on a landing page.

Never mix how-to and reference on one page. Split it into a how-to page and a reference page that link to each other.

Writing style​

  • Use a calm, professional, encouraging tone. Contractions are fine.
  • Never use marketing language: remove "effortlessly", "easily", "quickly", "best", "enhanced", "seamlessly".
  • Remove filler words: "simply", "on top of that", "in order to".
  • Never re-explain concepts. Link to Fundamentals pages instead. A one-sentence inline definition before the link is allowed when the task needs it: An entity is a set of fields attached to an event. See [entities](/docs/fundamentals/entities/index.md).
  • Use active voice: "the Collector receives events" not "events are received by the Collector".
  • Always address readers as "you".
  • Use "the user" for the reader's end users.
  • Refer to Snowplow as "Snowplow", not "we" or "our".
  • Stay in the present tense. Never use "currently", "now", "in the future", "latest", "Snowplow plans to".
  • Never use exclamation marks.
  • Use emojis only for information (✅ or ❌ in tables). Never use emojis for decoration.

Writing for retrieval​

Search engines and AI agents often read one section of a page, or one chunk of the Markdown copy, without the rest. Write every section so it makes sense on its own.

  • Never use "above", "below", "previous section", or "the following" to point at other content. Name it or link to it: see [Configure the tracker](#configure-the-tracker).
  • Put the exact error string next to its fix, in a code span or block, in the same paragraph or list item, so a search for the message finds the fix. Copy the string from the real output. Never paraphrase it.
  • Restate every diagram as numbered steps or a list in the text. The Markdown copy keeps the diagram's alt text but not its layout.
  • Repeat the subject in each section instead of "it" or "this": "The Enrich configuration file" not "This file".
  • Give version requirements with <AppliesTo>, not "available since version X" in prose, so the marker and the versions page can't disagree.
  • Keep tables as real Markdown or HTML tables, not images, so every row is in the Markdown copy.

Diagrams and images​

  • Always provide alt text.
  • Prefer Mermaid diagrams for architecture visuals.
  • Use descriptive file names: snowbridge-architecture.png not image.png.

Inclusive language​

  • Use "allowlist" and "denylist". Never use "whitelist" or "blacklist".
  • Avoid gendered language. Use plural or "they".
  • Use "person-hours". Never use "man-hours".
  • Describe links clearly. Use the target page name where possible.
  • Acceptable: see [Tracking specific events]() or the schema is found [here]().
  • Never lead with the link: [here]() is the schema.

Snowplow terminology​

  • Use "Snowplow". Never use "Snowplow Analytics".
  • Always capitalized: Event Studio, Snowtype, Snowplow Customer Data Infrastructure, Signals.
  • Console: Capitalized, no article. "Data structures in Console."
  • Collector: Capitalized, with "the". "Events hit the Collector endpoint."
  • Enrich: Capitalized. "Enrich can enrich an event."
  • Loaders: Capitalized, with "the". "The BigQuery Loader reads enriched events."
  • Iglu, Iglu Central, Iglu Server: Capitalized. Other Iglu components are lowercase.
  • Not proper nouns: entities, events, schemas, data structures, tracking plans, page view, self-describing event, source applications, failed events.
  • Use "entity". Never use "context".
  • Use "self-describing event". Never use "unstructured event".
  • Use "failed events". Never use "bad rows" (except for legacy JSON format).
  • Language capitalized, "tracker" lowercase: "JavaScript tracker", "Python tracker".
  • Use "native mobile trackers" for iOS and Android together.
  • Use "JavaScript tracker" for all web trackers collectively.
  • Call events without schemas "baked-in events" (page views, page pings, structured, legacy ecommerce).
  • Use "version 1.3.0" or "1.3.0". Never use "v1.3.0".

General technical terms​

  • Capitalize acronyms: HTTP, CDI, CLI, API, SQL, SDK, URL.
  • Pluralize naturally: APIs, SDKs, URLs. Never write "JSONs"—use "JSON schemas".
  • Match third-party official styling: Google, Snowflake, dbt, Kafka, npm.
  • "Real-time" as adjective. "Real time" as noun.
  • Always hyphenate: back-end, front-end, server-side, client-side.
  • No hyphen in "ecommerce". Capitalize only for product names: "Ecommerce plugin".
  • Use lowercase "web": "a web browser".

Markdown formatting​

  • Use - or * for bullet points.
  • Use triple backticks and specify the language for code blocks.
  • Use Docusaurus admonitions sparingly. Always set custom headings using bracket syntax: :::note[Title].
  • Use Tip for actions, Note or Info for information, Warning for data loss or security risks, Danger for pipeline outages.

Components​

These components are available in every MDX file without an import. See /style-guide/components/ for examples.

  • <Card> and <CardGrid>: link, product, quickstart, and compact cards. Never hand-write card markup.
  • <Button>: primary, secondary, ghost, or link. One primary button per region.
  • <Badge>, <TierBadge>, <VersionBadge>, <LifecycleBadge>, <LicenseBadge>, <Availability>: text badges. Never use shields.io images.
  • <CodeGroup>: the same example in several languages, as tabs in the code header. Use it instead of <Tabs> around code blocks.
  • <Steps>: a numbered rail. Write each step as a ### heading inside it. Never number headings by hand.
  • <ParamTable> and <Param>: configuration options and function arguments, with name, type, required, default, and since.
  • <TrackerTier id> and <IntegrationBadges id>: the support tier label at the top of tracker and integration landing pages, read from src/data/trackers.json and src/data/destinations.json. Never hard-code a tier with <TierBadge> on these pages.
  • <TrackerFeatures id>: a tracker's feature support from src/data/trackers.json, after the label row on tracker landing pages. To change what it shows, edit the manifest, not the page.
  • <FeatureMatrix>: comparison tables for catalog hubs, generated from a manifest in src/data/.
  • <AppliesTo>: an inline minimum-version marker from src/data/feature-versions.json.