PostHog Handbook Library / Docs and Wizard

2,287 words. Estimated reading time: 11 min.

# Style guide for writing docs

Auto TL;DR

## At a Glance

This long page covers these main areas. The list is generated from the article headings, so it updates with every handbook rebuild.

1. Tools to enforce style
2. Voice and tone
3. Address the reader directly
4. Use active voice
5. Use present tense
6. Be concise
7. Avoid unexplained jargon
8. Contractions

First, you should start with two assumptions about our users.

1. They're busy and have limited time.
2. They're not experts and don't know what we know.

This style guide helps you write docs based on these assumptions.

These are guidelines, not rules. They exist to keep our docs consistent and polished, but good judgement matters more than strict adherence when you're writing. If something makes the docs clearer, more helpful, or just plain better, do it.

See the style guide from the for additional writing guidelines.

---

### Tools to enforce style

Tools like prose linters and LLMs are effective at catching style guide violations that humans often miss. Use them to check your writing against this entire guide.

We apply style guides through multiple tools.

- Vale – enforces style guide rules through prose linting in PRs
- InKeep docs writer – an AI agent that uses style guides as context when drafting docs PRs
- Skill – (coming soon) agent skills that uses style guides as references for writing docs

---

### Voice and tone

#### Address the reader directly

Address the reader directly using "you" instead of "the user", "developers", or "we".

> Do: "You can create an insight by clicking New insight."

> Don't: "Users can create insights."

Use the imperative form and drop the "you" when giving instructions, commands, or guidance.

> Do: "Create an insight by clicking New insight"

#### Use active voice

Active voice makes it clear who or what performs an action.

> Do: "PostHog captures events automatically."

> Don't: "Events are captured automatically by PostHog."

Exception: Use passive voice when the actor is unknown or unimportant.

> Acceptable: "The data is encrypted at rest."

#### Use present tense

Write in present tense. Avoid future tense unless you are explicitly describing future behavior or outcomes.

> Do: "The insight displays your data."

> Don't: "The insight will display your data."

#### Be concise

Remove unnecessary words. Every clause should add either value or clarity.

> Do: "Click Save"

> Don't: "Now you can go ahead and click the Save button to save your changes"

#### Avoid unexplained jargon

When you introduce technical terms or acronyms, explain them on first use or link to a definition. Don't assume the reader knows what you're talking about.

> Do: "Create a cohort to analyze behavior. A cohort is a group of users who share common properties."

> Do: "Create a cohort — a group of users who share common properties — to analyze behavior."

> Don't: "Enable LTV analysis by configuring your CDP and syncing cohort data to the warehouse."

#### Contractions

Use contractions to maintain a conversational tone.

> Do: "That's it. The experiment is running."

> Don't: "That is it. The experiment is running."

---

### Product terminology

#### Capitalize product names

Always capitalize PostHog product names as proper nouns. Use "Product Analytics", not "product analytics".

> Do: "Use Session Replay to understand user behavior."

> Don't: "Use session replay to understand user behavior."

However, if you're referring to the general industry term or a feature that isn't specific to PostHog, use lowercase. For examples: "many companies offer product analytics."

#### Keys and tokens

| Term | Description | |------|-------------| | Project token | The public identifier (starts with `phs_`) used in SDKs and the snippet to send events. This is NOT an API key. Never call it `project API key`. | | Personal API key | A private key (starts with `phx_`) used for server-side API access. This IS an API key. | | Feature flags secure API key | A separate key used for local evaluation of feature flags. |

> Do: "Add your project token to the PostHog initialization code."

<!-- vale PostHogBase.ProjectToken = NO -->

> Don't: "Add your project API key to the PostHog initialization code."

<!-- vale PostHogBase.ProjectToken = YES -->

#### PostHog platform

| Platform term | Description | |---------------|-------------| | PostHog | Use by default. Refers to our cloud platform. Most users are on cloud, so do not specify "Cloud" unless differentiating from self-hosted. | | PostHog Cloud | Only use when explicitly differentiating cloud features from self-hosted deployments. | | Self-hosted PostHog or hobby deployments | Use when referring to self-hosted installations. |

> Do: "Go to Insights in the PostHog app and click New insight."

> Do: "This feature is only available on PostHog Cloud."

> Don't: "To create an insight on PostHog Cloud, go to the Insights tab."

---

### Grammar and mechanics

#### Use American English

PostHog is a global company. Our team and our customers are distributed around the world. For consistency, we use American English spelling, grammar, date, and time formatting.

> Do: color, analyze, behavior, license

> Don’t: colour, analyse, behavior, licence

#### Sentence case for headings

Use sentence case for all headings. Capitalize only the first word and proper nouns like our products.

> Do: "## How to create a feature flag"

> Do: "## Get started with PostHog Feature Flags"

> Don't: "## How To Create A Feature Flag"

#### Oxford comma

Always use the Oxford comma.

> Do: "PostHog offers analytics, session replay, and feature flags."

> Don't: "PostHog offers analytics, session replay and feature flags."

#### Numbers

- Spell out numbers zero through nine
- Use numerals for 10 and above
- Use numerals for percentages, measurements, and technical values

> Do: "You can create three dashboards" or "You can create 15 dashboards."

> Do: "Set the timeout to 30 seconds."

#### Use straight apostrophes and quote marks

Many writing tools, such as Google Docs, Notion and Word, add curly quotes and apostrophes. Please avoid using these. They can normally be turned off in the settings.

#### Use British-style en dashes

While we default to American English in most things, we prefer using the British-style en dash ( – ) with a space either side rather than the longer em dash with no spaces (—) used in American English.

Please don't use a hyphen instead of en dash. On Macs, holding down Option and the hyphen key will give you an en dash.

> Do: "Don’t up vote your own content, and don’t ask other people to – post it and pray."

> Don't: "Don't up vote your own content, and don't ask other people to—post it and pray."

---

### Word choice

#### Acronyms

Use all caps for acronyms and initialisms.

> Do: SQL, API, HTML, CSS, JSON, REST, HTTP, URL, SDK, CLI, UI, UX

> Don't: Sql, Api, Html

Follow official capitalization for branded technologies.

> Do: GraphQL, WebSocket, PostgreSQL

#### Choose simple words

Choose simple, common words over complex alternatives.

| Instead of | Use | |------------|-----| | utilize | use | | facilitate | help | | commence | start, begin | | subsequent | next | | prior to | before |

#### Use precise verbs

Use precise verbs that clearly describe the action being performed.

| Vague | Specific | |-------|----------| | use the API | call the API | | work with data | query data, analyze data | | handle errors | catch errors, log errors | | manage users | add users, remove users, assign roles |

#### Inclusive language

Prefer neutral, inclusive terms.

| Instead of | Use | |------------|-----| | blacklist/whitelist | denylist/allowlist | | sanity check | validation, verification | | master/slave | primary/secondary |

#### Avoid phrases that trivialize

Avoid words or phrases that trivialize the work. They can sound dismissive or minimize the reader's efforts.

Don't use words like "simply", "just", "easily", "obviously", "of course", and "clearly".

> Do: "Add the SDK to your project."

> Don't: "Simply add the SDK to your project."

---

### Formatting and structure

#### Use descriptive headings

Headings should clearly and explicitly describe what's in the section. Prefer action-oriented titles over nouns and gerunds.

> Do: "## How to create a feature flag"

> Don't: "## Feature flag creation"

> Do: "## Customize styles and layouts"

> Don't: "## Customization"

#### Use short paragraphs

Avoid paragraphs longer than 3-4 lines. Break up longer content with line breaks, subheadings, lists, or visual elements as needed.

#### Bulleted lists

Use bullets for unordered items of equal importance. Default to prose when 1-2 items would be clearer as a sentence.

> Do:

> PostHog offers several products:

> - Product Analytics

> - Session Replay

> - Feature Flags

> - Experiments

> Don't:

> Feature flags let you:

> - Control feature rollouts

#### Numbered lists

Use numbered lists when ordering, ranking, or hierarchy matters.

> Do:

> 1. Click New insight

> 2. Select your event

> 3. Click Save

#### Definition-style lists

When listing items with descriptions, use a dash ( - ) to separate the item from its description. Don't use a colon.

> Do:

> - Product Analytics - Track user behavior and measure conversions

> - Session Replay - Watch real user sessions to debug issues

> - Feature Flags - Control feature rollouts and run experiments

> Don't:

> - Product Analytics: Track user behavior and measure conversions

> - Session Replay: Watch real user sessions to debug issues

> - Feature Flags: Control feature rollouts and run experiments

#### Punctuation in lists

Use a period when each item is a complete and standalone sentence (has a subject and verb and is an independent thought).

Don't use a period when items are phrases or fragments that complete an introductory phrase.

Be consistent within a single list. If one item is a partial sentence, make all items partial sentences.

> Do:

> PostHog offers several products:

> - Product Analytics

> - Session Replay

> - Feature Flags

> Do:

> Use feature flags to:

> - Control rollouts to specific users

> - Run A/B tests on new features

> - Disable features without redeploying

> Do:

> There are multiple ways to fetch data from PostHog.

> - You can use the API.

> - You can use the SDK.

> - You can use webhooks or data pipelines.

> Don't:

> To set up PostHog:

> - Install the SDK.

> - Configure your project token.

> - Start capturing events.

#### Tables

Use tables for listing multiple items across multiple attributes. When a bulleted list isn't easy to scan, try using a table instead.

| Plan | Events | Team members | Price | |------|--------|--------------|-------| | Free | 1M | Unlimited | $0 | | Paid | 2M+ | Unlimited | $0.00031/event |

> Don't:

> Our plans:

> - Free: 1M events per month, unlimited team members, $0

> - Paid: 2M+ events per month, unlimited team members, $0.00031 per event

#### Bold text

Use bold for structured information and visual formatting like callout labels, definition lists, and problem/solution patterns.

- Callout labels - `**Note:**`, `**Important:**`, `**Warning:**`, `**Tip:**`
- Definition lists - `**Term** - Description` patterns
- Problem/Solution labels - `**Problem:**` and `**Solution:**` in troubleshooting docs

> Do: "Note: Use feature flags to control rollouts."

> Do: "Problem: Events aren't appearing in the dashboard."

Avoid using bold text for general emphasis in prose. If something is important and needs extra emphasis, consider using a callout box instead.

> Don't: "This is a really important step in the process."

> Don't: "Make sure you always configure this setting before deploying."

#### Bold UI elements

Use bold for UI elements like buttons, menu items, labels, and text fields. Don't use quotes.

> Do: Click New insight in the Insights tab.

> Don't: Click the "New insight" button.

For nested UI elements, use `>` to connect them hierarchically.

> Do: In PostHog, navigate to Settings > API keys > Personal API key.

> Don't: In PostHog, navigate to Settings, look under API keys, and then click Personal API key.

#### Avoid excessive formatting

Don't use:

- Multiple header levels in short sections
- Bold text for general emphasis in prose
- Lists when prose is clearer
- Too many callout boxes

#### Links

##### Wikipedia-style internal links

Link the first mention of a PostHog term, feature, or SDK on a page to its docs page.

> Example: "To create an insight, first capture events. Then, select the data you want to see."

##### Link to the PostHog app

Link directly to PostHog in-app pages using `https://app.posthog.com/`. Users are redirected automatically to the correct US or EU subdomain.

> Do: "Go to the Insights tab and click New insight."

> Don't: "Go to the Insights tab and click New insight."

> Don't: "Go to the Insights tab and click New insight."

##### Link text

Link text should describe the destination. Avoid generic text like "click here" or "this page."

> Do: "See our installation guide for instructions."

> Don't: "Click this link for installation instructions."

---

### Code

#### Use backticks

- Inline code - Use single backticks for code elements or values in prose like `posthog.capture()`
- Code blocks - Use triple backticks for multi-line code blocks

#### Follow language conventions

Use the standard style conventions for each programming language:

- JavaScript/TypeScript - `PascalCase` for classes, `camelCase` for functions and variables, ES modules (`import`/`export`) instead of CommonJS (`require`)
- Python - `PascalCase` for classes, `snake_case` for functions and variables
- HTML - Lowercase for elements and attributes

#### PostHog event and property naming

Always use `snake_case` for PostHog event and property names:

    posthog.capture('user_signed_up', {
        user_id: '123',
        username: 'Jane Doe',
    })

Never use `camelCase` or `PascalCase` for event or property names.

#### Show real-world examples

Use realistic examples that demonstrate actual use cases.

> Do:

> ```js

> posthog.capture('purchase_completed', {

> product_id: 'prod_12345',

> revenue: 49.99,

> currency: 'USD'

> })

> ```

> Don't:

> ```js

> posthog.capture('event', {

> property: 'value'

> })

> ```

#### Comment sparingly

Only add comments when code isn't self-explanatory:

    // Don't show the survey if user dismissed it in the last 30 days
    if (lastDismissed > Date.now() - 30 * 24 * 60 * 60 * 1000) {
        return
    }

---

### Screenshots and media

It's extremely important to ensure screenshots or videos don't show any personal or sensitive user information like emails, phone numbers, or other identifying details.

#### Screenshot requirements

To maintain consistency and clarity:

- Focus on the relevant UI - Exclude sidebars and irrelevant interface elements
- Use standard viewport - Set device width to 1000-1400px in devtools
- Use annotations – Add arrows, text, or other visual elements to highlight specific UI elements

#### When to use videos

Use videos for:

- Multi-step workflows
- Complex interactions
- Demonstrating UI behavior

Use Screen Studio with these settings:

- Use the preset
- Remove zoom-in for clicks
- Export: MP4, 1080p, 60 fps, "web" quality

Canonical URL: https://posthog.com/handbook/docs-and-wizard/docs-style-guide

GitHub source: contents/handbook/docs-and-wizard/docs-style-guide.mdx

Content hash: `27e63d37110fccc4`

Static reader notes

- `MDX_COMPONENT_STATIC_ADAPTER`: Adapted interactive MDX components for static reading: CalloutBox, SmallTeam.