Style guide

This style guide explains our guidelines for contributions to PostHog's documentation, tutorials, and blog.

General principles

Assume almost nothing

As you gain mastery of a product or feature, some things become second nature, but remember they weren't always so obvious. Call these out, and provide links to relevant docs or websites.

Make it easy for your reader to implement their feature or solve their issue, whether they are an expert or just starting out with PostHog.

Avoid hedging

We are opinionated at PostHog. That means avoiding hedging like saying "it's complicated" or "it depends." This is frustrating for the reader and doesn't add value. Instead:

Have an opinion.
Provide an example.
Do the research until you can do 1. or 2.

Avoid overly long intros

Most articles can be improved by making the intro shorter and more direct. Two short paragraphs, or less, is preferable, though there will always be exceptions.

Brand guidelines

We're an analytics platform, not a product analytics tool

Unless directly referring to our product analytics suite, substitute references to "product analytics" or "product analytics tool" with the phrase "analytics platform".

Example: “A data warehouse or product analytics tool like PostHog can be helpful here.” would become “A data warehouse or analytics platform like PostHog can be helpful here.

Product OS is also an acceptable alternative – use your judgement based on the context.

Do not capitalize product features

It's "product analytics" not "Product Analytics" and so on.

Style rules

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 and grammar.

Use the Oxford comma

Write "bananas, apples, and oranges", not "bananas, apples and oranges".

Why does this matter? Consider the old joke:

"There are two hard problems in computer science: naming things, cache invalidation, and off by one errors."

That doesn't work without the Oxford.

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.

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

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.

Use "enable", not "allow"

Allow is another way of saying permit.

Example: Your partner allows you to stay up late and play video games.

Enable means providing the means or opportunity.

Example: PostHog enables you to understand user behavior.

In most cases, PostHog enables users to do things.

Add extra line breaks between long bullet points

Sections with long bullet point items are hard to read without extra line breaks (when looking at Markdown). For example, this passage:

Feature flags: PostHog offers robust, multivariate feature flags which support JSON payloads. This enables you to push real-time changes to your product without needing to redeploy. Visit our feature flag page for more information. LogRocket doesn’t have any in-built feature flag functions.
Experiments: PostHog offers multivariate experimentation, which enables you to test changes and discover statistically relevant insights. Visit the experimentation page for more information. LogRocket doesn’t have any in-built experimentation features.
Open source: PostHog is entirely open source, under a permissive MIT license. The biggest advantage for users is the ability to build on top of PostHog and to access the source code directly. Our team also works in the open. LogRocket is not an open source company, nor is the product available under an open source license.

Is harder to read than this passage:

Feature flags: PostHog offers robust, multivariate feature flags which support JSON payloads. This enables you to push real-time changes to your product without needing to redeploy. Visit our feature flag page for more information. LogRocket doesn’t have any in-built feature flag functions.
Experiments: PostHog offers multivariate experimentation, which enables you to test changes and discover statistically relevant insights. Visit the experimentation page for more information. LogRocket doesn’t have any in-built experimentation features.
Open source: PostHog is entirely open source, under a permissive MIT license. The biggest advantage for users is the ability to build on top of PostHog and to access the source code directly. Our team also works in the open. LogRocket is not an open source company, nor is the product available under an open source license.

This isn't necessary for shorter bullet point lists.

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.

Capitalize proper names as appropriate

Write "Redis server", not "redis server".

"Open source" vs "open-source"

Both can be correct depending on usage.

Open source should be hyphenated when it appears before a noun.

Example: "The open-source community is awesome"

But should be written without a hyphen in other contexts.

Example: "PostHog loves being open source."

Capitalize acronyms and define where needed

Write "URLs", not "urls".

Many acronyms, like that one, will be familiar to developers. When in doubt, link the first use of an acronym to a definition, or provide one.

Use sentence case for titles

Write "Documentation style guide", not "Documentation Style Guide".

Technical writing

Follow these guidelines when writing docs, tutorials, or any other content that explains how to use PostHog.

Wikipedia-style internal links

The first mention on a page of a PostHog term, feature, or SDK should link to its docs page.

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

Link to PostHog app

You can also link to the PostHog app directly by using https://us.posthog.com/${path}. This saves time for our users and makes it easier for them to find what they need. Make sure to remove project/2/ from the URL so it redirects them to their project. EU Cloud users are redirected automatically.

Example: "To create an insight, first capture events. Then, go to the insights tab and click + New insight."

Bold button and tab names

Put button, tab, and other navigation names in bold. This makes it easier for our users to skim through the docs, and it's cleaner than using quotes all the time.

Example: "Go to the insights tab and click + New insight."

The backtick is your friend

Remember to use backticks around inline code snippets, and triple backticks around multiline code samples.

Follow the style standards of each programming language

In code samples, use the conventions of the language the code is written in.

For example, JavaScript uses PascalCase for class/constructor names, and camelCase for most other names. Python uses PascalCase for classes, and snake_case for most other names. And so on.

Use snake case for PostHog events and properties.

Use snake_case, not camelCase or PascalCase for PostHog event and property names. For example:

JavaScript

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

Record videos

For flows with many steps, it's often more helpful to include a video instead of a screenshot. We use Screen Studio to record videos. Feel free to buy yourself a license.

Use the following settings:

Preset
Remove any zooming-in for clicks, as this can sometimes make videos hard to follow.
For exporting: use MP4, 720, 60 fps, and "web" quality