Style guide for writing docs

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

Editorial Team

Editorial Team

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."

PostHog platform

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, behaviour, 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.

Use precise verbs

Use precise verbs that clearly describe the action being performed.

Inclusive language

Prefer neutral, inclusive terms.

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

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 API key.
• 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.

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:

JavaScript

PostHog AI

posthog.capture('purchase_completed', {
    product_id: 'prod_12345',
    revenue: 49.99,
    currency: 'USD'
})

Don't:

JavaScript

PostHog AI

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

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