Overview

At PostHog, we want our docs to win over developers and give us a competitive edge.

The focuses on delivering a delightful developer experience, maintaining a well-organized knowledge base, and writing documentation that is a genuine pleasure to read for both humans and robots.

Our team's values

1. Treat docs like a product
2. Be practical, not just technical
3. Great docs start with writing
4. Teach the robots
5. Help our customers win

1. Treat docs like a product

We treat our docs like a product because they are. They have users (readers and AI agents), use cases (implementation, education, troubleshooting, etc.), and success metrics (more on this later).

Documentation presents unique challenges and opportunities. But ultimately, great docs drive product activation by providing the right information, in the right way, at the right stage in a developer's journey.

This means helping developers set up their very first PostHog event and helping existing customers with complex configurations integrate their third or fourth PostHog product. It also means enabling our docs to be used as context for AI workflows. It's a wide spectrum, but the goal is the same: help developers self-serve and succeed with PostHog.

Docs are a core part of the product experience. So when you're working on them, take some time to ask:

• Where is the reader on their PostHog developer journey?
• Where do they need to go next?
• How does this help them get there?
• Can the reader use this as valuable context for AI?

2. Be practical, not just technical

Developers don't want abstract examples or out-of-context code snippets. They want to solve real problems and use cases.

We want to showcase code that's runnable, practical, and immediately useful.

As a rule of thumb, our docs should show code within application context whenever possible. The examples we provide should reflect how PostHog is actually used in production, in the wild.

Isolated example:

posthog.capture({
  distinctId: 'distinct_id_of_the_user',
  event: 'user_signed_up',
  properties: {
    login_type: 'email',
    is_free_trial: true,
  },
})

If a code snippet has missing application context or business logic, it can be improved.

In-context example:

// Importing PostHog into the app

// Initializing PostHog client
const posthog = new PostHog(
  '<ph_project_token>',
  { host: 'https://us.i.posthog.com' }
)

app.post('/api/signup', async (req, res) => {
  const { email, password } = req.body

  try {
    const user = await createUser({ email, password })
    // Calling PostHog inside business logic // HIGHLIGHT
    posthog.capture({ // HIGHLIGHT
      distinctId: user.id, // HIGHLIGHT
      event: 'user_signed_up', // HIGHLIGHT
      properties: { // HIGHLIGHT
        login_type: 'email', // HIGHLIGHT
        is_free_trial: true // HIGHLIGHT
      }, // HIGHLIGHT
    }) // HIGHLIGHT
    res.status(201).json({ message: 'Signup successful', userId: user.id})
  } catch (error) {
    res.status(500).json({ error: 'Signup failed' })
  }
})

The in-context example is more verbose, but much more useful. It shows how PostHog fits into applications, which helps developers understand when and where to use it.

3. Great docs start with writing

Writing is something we love to do here at PostHog. The principles of PostHog writing and marketing all still apply here.

But documentation has a few unique demands.

People come to our docs looking for answers, usually with limited time. We focus on precise and consistent writing because they contribute to a smoother, more efficient learning experience.

Docs need to be finely tuned. Even small oversights or tiny mistakes can create snags that confuse readers. So nitpicking isn’t just allowed, it’s encouraged!

<summary>Nitpick #1</summary>

~~Just~~ Click Save ~~and the insight will be created~~ to create an insight.

<summary>Nitpick #2</summary>

~~Events are captured automatically by PostHog.~~ PostHog captures events automatically.

Nits and semantics and formatting (oh my!) – they're all part of the fun of technical writing. Careful attention to detail is what turns good docs into great ones, so don't shy away from it.

This does not mean our docs have to be dry or academic. In fact, they should have a natural flow that makes them easy to read. Be open, direct, and opinionated. Don't be afraid to add humor and personality when there's opportunity.

PostHog's writing voice is one of the key things that sets us apart from a sea of generic SaaS platforms. It's important that this voice can come through in our docs.

The docs style guide is a key reference we'll continue to update with examples and best practices.

4. Teach the robots

Robots aren’t a future concern. They're already here, and they're changing how people discover, evaluate, and use PostHog.

AI workflows depend on accurate and up-to-date context. Our documentation, the knowledge base, is the largest maintained source of natural language context we have. LLMs read our docs. Developers paste them into prompts. Agents use them as skills.

In other words, our docs teach AI how to be useful.

The AI wizard is a direct outcome of this philosophy. An agent that automatically integrates multiple PostHog products across frameworks, the wizard is the fastest way to activate PostHog because it consumes our docs as structured, on-demand context. It closes the gap between curiosity and real usage.

Making this possible requires context engineering and shaping our documentation into a moving, living system. We code as much as we write.

5. Help our customers win

Our customers are smart, discerning, and ambitious. They're here to build. They want to 10x their own products.

Our docs exist to help them win.

This means we should include details beyond references and technical implementations. We should share examples, use cases, and the big picture reasons why they should use a product or feature.

How we prioritize

Here's how we loosely define high-priority docs work:

• Anything that blocks product adoption or severely impacts the product experience
• Anything that speeds up new content velocity or improves overall quality
• Anything that unblocks better LLM-assisted workflows
• Usable docs (e.g., SDK references) come first. Cool docs (e.g., interactive code editor) come after

Measuring success

Our north star indicators that tell us if our docs are heading in the right direction:

• Praise for how awesome our docs are (#brand-mentions, #posthog-feedback, etc.)
• More docs transformed into high-quality context for AI agents
• Fewer support tickets caused by bad or missing docs
• More docs used by customer facing teams as a valuable self-serve resource
• More docs pageviews (within context)