Add the new getting started content

[daniloc]

Changes

This adds the new getting started sequence, ahead of installation.

Admonition component

This pull also adds a new Admonition component, in the style of Docusaurus.

It's a weird name, but a handy component to have. These let us set off important content to improve skimmability, with these helpful cues:

• Icon
• Title
• Colors

The visual breaks from Admonitions are essential to encapsulate the many thinking-and-planning steps at the early stages of a PostHog integration. Tested and working with dark mode.

⚠️ Infohazard warning: I don't reason very well in Tailwind and LLM assistance was used to get the styling just right. Special attention should be paid to Admonition.js in review.

Outstanding issues

Doing a PostHog integration requires some planning for a product/team that wants to do well. This content prompts the reader to do it, but I've not yet found the right way to present those planning activities in the read-only docs context. This all works better in the forkable repo:

https://github.com/PostHog/posthog-integration-planner/tree/main

At the same time, for SEO purposes, it would be a crime not to represent this stuff in the main docs.

But then we have to maintain two sets of the same content? I don't know if I like that.

Additional tasks outstanding

• Intro terms and concepts re: @andyvan-ph's suggestion
• 'Read more' links pass
• Formatting pass
• Figure out how to present the planning activities

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
posthog	✅ Ready (Inspect)	Visit Preview	Feb 21, 2025 3:47am

[andyvan-ph]

Alrighty, haven't consumed this in much detail yet, but some early thoughts:

• I strongly think we shouldn't mess with the current 'New to PostHog' bit. Having this be the first thing just feels wrong, since our docs are mostly for engineers and first thing they'll want to do is install, so it ought to start there.

• We should totally get some custom versions of the illustrations before we go live. I figure this was the plan anyway, but flagging just in case.

• I don't love "Winning on purpose" as a page title / sidebar thing. It's the wrong tone for the docs.

On the sidebar, I think we should do something like this:

Docs
- Overview

Install PostHog
- Start here
- SDKs
- Framework guides
- Reverse proxy
- Migrate
- Advanced

Getting started / New to PostHog
- Overview (covering core concepts / what we call things etc.)
- Winning on purpose (I don’t love this name)
- Measuring activation
- Tracking retention
- Capturing revenue

Product OS
- What is Product OS?
- API
- And so on

Obviously this extends the sidebar quite a bit (we can figure that out how to make this better later), but this feels like a more natural sequencing.

[andyvan-ph]

Looking at the click map, I reckon there's a version of the sidebar where Reverse proxy, Migrate and Advanced live somewhere else so the new Getting started guides are higher up in the mix.

[andyvan-ph]

Alternative sidebar idea:

Docs
- Overview

Install PostHog
- Start here
- SDKs
- Framework guides
- Reverse proxy

Getting started / New to PostHog
- Overview (covering core concepts / what we call things etc.)
- Winning on purpose (I don’t love this name)
- Measuring activation
- Tracking retention
- Capturing revenue

Product OS
- What is Product OS?
- API
- And so on

• Migrate could move into the 'Resources section'
• The contents of 'Advanced' could be distributed elsewhere pretty easily, imo. CDP guide could be in 'Start here'. We could sneak 'Browser extensions' into framework guides, the CSP page could probably go into resources somewhere and be linked to from various other places to discoverability.

[daniloc]

Thanks to ongoing gut checking from @andyvan-ph the last couple weeks, I think we've got a good foundation for new users who want to understand WHY they use PostHog, beyond the nuts and bolts of installation. This is five meaty new pieces of content, a reorg of the main docs menu, and a new component to let us be more expressive with info boxes.

@ivanagas @andyvan-ph have a look around and tell me what you think. Once we're in agreement we'll get some more eyes on it, and hopefully this can ship sometime next week.

[ivanagas]

Ok, some thoughts.

I don't want to nitpick this to death and I get the broad goal of creating motivation to install and onboard into PostHog, but I don't think it accomplishes it well enough yet.

1. Feels like a conceptual onboarding to some of product analytics rather than the entire platform.
2. Feels like it spends too much time explaining PostHog features like funnels and retention charts to really be about concepts and motivations.
3. Maybe this means that it is just too long

I think we should think hard about who this is/isn't written for as well as the goals we want it to accomplish for those people. My mental models of users is that they probably have familiarity with some basic product analytics, but need a bridge to more advanced ones (or other products).

Of course, I could be wrong if we have examples from users, sales calls, etc. to back this up, I'd love to read those.

[ivanagas]

This is very nice 😎

[andyvan-ph]

It is, though could use a different name than Admonitions? This being very nitty, but it's weirdly over elaborate name for "really nice boxouts" and I anticipate typing it frequently will get very tiresome. maybe just call them 'callouts' or something like that?

(I don't feel strongly, obv)

[daniloc]

It is, though could use a different name than Admonitions?

It is a COMPLETELY awful word, and I can't stand how it feels on the proverbial tongue.

The argument for using it – and I join you in also not ultimately feeling strongly – is that it's become the common name for this across multiple developer docs projects, somehow.

https://www.google.com/search?client=safari&rls=en&q=developer+documentation+admonition&ie=UTF-8&oe=UTF-8

"Callout" would be what I'd name it too, but is there any upside to maintaining convention for future contributors?

[ivanagas]

The big problem I have with this is that PostHog is more than just product analytics. I'm not even sure it is a good place to start. Web analytics, autocapture, and session replay (maybe even surveys) are all likely more useful in the earliest days.

[ivanagas]

Basically like this: https://posthog.com/founders/early-stage-analytics

[andyvan-ph]

the way I'm thinking about this is this is just V1. it makes sense to start with product analytics mainly because:

1. it's harder to onboard than replay or web analytics, so some people need more help
2. it's still the product most people choose to onboard first ~50% atm.
3. we can add more broader platform stuff down the line – e.g. a section on solving user problems that can intro replay, error tracking, and surveys / using posthog for support, and so on

[ivanagas]

Can success be boiled down to setting a specific metric and trying to optimize for it? I feel like this isn't true as a core principle.

[ivanagas]

If you are using Stripe or Chargebee, you don't even need to care what revenue capture looks like, you can just connect your source and query it.

The real tricky part is what that query looks like. As far as I know, we can get some basic revenue metrics, but more complex ones like MRR are still not easy to set up.

[ivanagas]

Also, think about the goal of this: motivating people to install PostHog. It feels like we shove a lot of concepts that don't help us with this goal like talking about event naming.

[daniloc]

motivating people to install PostHog. It feels like we shove a lot of concepts that don't help us with this goal like talking about event naming.

Oh, interesting. No, the goal is not getting people to install PostHog.

People install PostHog and get docs guidance for doing so by onboarding into the product and following the workflow with the little platform picker and snippet provider.

The goal here is to get people to use their integration for the greatest possible leverage, and to have the shared mental model to not fuck it up.

[ivanagas]

Could it be part of this section then?

https://posthog.com/products

[daniloc]

Could it be part of this section then?
posthog.com/products

I feel confident this content belongs in docs. Here's why:

If the ceiling on our docs is model field tables, explanations of function calls, and rote instruction on which function to call to achieve a given outcome, that limits our impact.

1. Sales has to repeat itself a lot, and building consensus inside the customer organization is an ongoing slog. These docs are written based on the most common stuff sales has to hammer home all the time to get people to actually succeed with PostHog, for the most common business case we encounter: B2B or B2C companies with fixed, recurring revenue models.
2. Only customers who have a relationship with sales will get cohesive guidance on laying their basic metrics foundation. Everyone else will have to either hunt around dozens of blog posts to assemble this context, or give up.
3. The overall mental model of what you get from measuring business outcomes fails to propagate.

So we get this right, we help multiply the impact of every person selling PostHog, we improve the likelihood that smaller teams who aren't yet working with sales get further, and everyone can know what to actually do for maximum impact after the snippet is installed.

I got to ride shotgun while a PostHog integration went sideways. Brand new startup, tiny team, relatively simple communication structure. Smart guys. But they had zero model of things like activation (which they desperately needed to measure) and everything went more poorly for it. They just didn't understand what PostHog was for in their mission, nor did they know where to start to build their confidence in the path forward. And we had no artifacts that could weave this stuff together in a coherent, efficient way. I wasn't going to get a seed-stage CEO to read a dozen blog posts, you know?

Related, I got this email the other day, following up on a docs-related gripe from a new user:

As part of a team that's relatively new to analytics, we find PostHog's vast array of features a bit overwhelming. A basic "getting started" guide—something like a simple to-do list after installing the SDK—would be immensely helpful.

Right now, it's easy to get lost in the documentation. The content is extensive and well-structured, but for someone completely new to analytics, it can feel a bit tedious to navigate. While the current docs are great for users starting with PostHog, they might not be as approachable for those who are new to analytics in general.

[andyvan-ph]

Adding some of my general thoughts to this thread:

This does belong in docs imo, it's more a question of when and how. I think the first 'Getting HogPilled' page is a weird entry point for docs overall because it starts with lots of high-level concepts, rather than the product / platform itself. We could fix this in a couple of ways:

1. Just move the Install / integrates section above this. Danilo and I have debated this a lot already, though I like the provocation here to try something different. One argument against having 'Getting HogPilled' first is a lot of what this guide covers is how to be successful with PostHog AFTER you've installed it. Using that logic, it would make sense to put this stuff after the install guides.

2. Start with a broader 'What is PostHog?' page first – i.e. a much better version of the What is Product OS? page that introduces the core part of the product and how they fit together.

Fwiw, I think the answer may be to do both. Start with the install guides, but add a 'What is PostHog?' page before Getting HogPilled anyway.

[daniloc]

My mental models of users is that they probably have familiarity with some basic product analytics, but need a bridge to more advanced ones (or other products).

Of course, I could be wrong if we have examples from users, sales calls, etc. to back this up, I'd love to read those.

So some valuable context here: I wrote these by interviewing Cameron like five times, trying to get to the most common issues that sales needs to address over and over again with newbies. These are the blockers, from that vantage, that impact how successful people are with the product.

[andyvan-ph]

I've left various comments inline / on existing threads. Other final thoughts / next steps:

• I'm still not totally convinced it makes sense to start with this above the install guides. I go into this in more length in the thread so won't repeat here.

• I like the execution here. it feels very tight and i can see where we can expand on this starting point. there are bits i'd like tighten up or clarify, but we can get to line edits / suggestions later

next steps:

1. I guess it would makes sense for @daniloc to digest feedback so far, make any changes he wants and we can do another round of feedback tomorrow / monday

2. we should use our sprint meeting on monday to discuss any of the more complicated decisions

[andyvan-ph]

the way I'm thinking about this is this is just V1. it makes sense to start with product analytics mainly because:

1. it's harder to onboard than replay or web analytics, so some people need more help
2. it's still the product most people choose to onboard first ~50% atm.
3. we can add more broader platform stuff down the line – e.g. a section on solving user problems that can intro replay, error tracking, and surveys / using posthog for support, and so on

[andyvan-ph]

Adding some of my general thoughts to this thread:

This does belong in docs imo, it's more a question of when and how. I think the first 'Getting HogPilled' page is a weird entry point for docs overall because it starts with lots of high-level concepts, rather than the product / platform itself. We could fix this in a couple of ways:

1. Just move the Install / integrates section above this. Danilo and I have debated this a lot already, though I like the provocation here to try something different. One argument against having 'Getting HogPilled' first is a lot of what this guide covers is how to be successful with PostHog AFTER you've installed it. Using that logic, it would make sense to put this stuff after the install guides.

2. Start with a broader 'What is PostHog?' page first – i.e. a much better version of the What is Product OS? page that introduces the core part of the product and how they fit together.

Fwiw, I think the answer may be to do both. Start with the install guides, but add a 'What is PostHog?' page before Getting HogPilled anyway.

[andyvan-ph]

would be nice to see an example of what revenue reporting would look like here. ideally a revenue dashboard of some kind would be cool. would be great for demonstrating the power of what you can track in posthog which is, basically, your entire business.

[andyvan-ph]

this section feels a bit vague to me. it either needs more detail on how to use these integrations, or a more obvious onward journey to learn how to track revenue using these integrations.

[andyvan-ph]

I think the diagram would actually be better at the bottom of the page – i.e. explain the concepts first, then bring in the diagram showing how they fit together.

[andyvan-ph]

It is, though could use a different name than Admonitions? This being very nitty, but it's weirdly over elaborate name for "really nice boxouts" and I anticipate typing it frequently will get very tiresome. maybe just call them 'callouts' or something like that?

(I don't feel strongly, obv)

[andyvan-ph]

I feel like this retention section ends on a weird not. like, i'm expecting a final point or some further reading. i suppose we could send people to stuff around how to improve retention?

[camerondeleone]

Wanted to weigh in here on the genesis of this from the sales/cs side. Apologies in advance for the wall of text.

tl;dr I was thinking of this as some kind of 'module' that people who are really new to analytics in general would find useful, the most 'handholding' version of how to think about metrics.

idk exactly where or how people ought to discover it, but I really liked what wordware has on their website: a checkbox for "i''m technical"

Not advocating for putting this somewhere that prominent, as obviously the appeal of this type of content is low/zero for our hardcore ICP, and the docs/onboarding should probably default cater to them. However I noticed — especially in the AE role when trying to onboard new users to accounts, but also selling to startups — that there is a distinct set of users who don't already 'get' the mental model for event based analytics, our core product. This is pretty foundational to not screwing up your PostHog setup, or understanding billing and querying, esp in a multi-product scenario, so for those who do self-serve from 0, we want something.

Prior to this work, we had a few tutorials, some more autobiographical ("how we found our activation metric") and some more plainly instructuve (pirate metrics, etc), and the data model work Danilo did, but none that were really a series of starting from the most basic 'how to think about analytics' with the why from someone coming from a non-technical or non-analyst background. We conceived of this as solving the problem of explaining the basic concepts and objects in PostHog from the perspective of someone totally naive to analytics, because sales occasionally runs into these folks — they're using PostHog because it's the shiny new thing, nice UI etc, but really they haven't grokked the value prop — maybe someone else at their co has made the decision to use it, or maybe they just think it looks pretty and know they 'need to be more data driven' or whatever. So I wanted a standalone set of articles or worksheets that could help those people.