Sharing instructions between docs, in-app onboarding, and wizard #362

gewenyu99 · 2025-09-03T20:37:08Z

Always up to date instructions maintained in a single place. Important for our sanity and for 🚀 growth.

joshsny

Very nice RFC 🙌

I've put some notes to get us thinking

joshsny · 2025-09-08T19:16:20Z

requests-for-comments/2025-09-02-shared-instructions.md

+
+### Better troubleshooting workflow
+
+Another part of the problem is that only the in-app onboarding instructions have real-time feedback on if the user's on the right track. They do this by showing if a event has been received by PostHog.


Slight aside from the RFC, but it'd be great if we put some of this feedback for users into the website, I know that's hard now as we don't share auth state much between them

Yeah this is a part of my plans 🙈 We'll need this for docs and for the wizard.

I'd love to get some help on this, I haven't touched the mono repo much, but I'd love to do a PR. Always an itch to write some code for me.

joshsny · 2025-09-08T19:17:31Z

requests-for-comments/2025-09-02-shared-instructions.md

+
+We can take this concept further by adding clear checkpoints and troubleshooting instructions to the wizard, docs, and in-app onboarding. 
+
+These instructions will be slightly different between the docs, in-app onboarding, and wizard because they're displayed in different contexts. Some of these checkpoints could be API calls, prompts for the wizard, or instructions for the user to follow.


I was thinking about the checkpoints recently, I think for the wizard, we should provide specific checkpoints like check-event-ingested etc. that we can put as a step in a guide, which will trigger it to check that step.

👍 YES that's the idea. We have these for docs already, but they'll obv be different for wizard. Probably an API we can hit? But if we expose an API, we can use it in docs, too?

joshsny · 2025-09-08T19:19:20Z

requests-for-comments/2025-09-02-shared-instructions.md

+
+We can take this concept further by adding clear checkpoints and troubleshooting instructions to the wizard, docs, and in-app onboarding. 
+
+These instructions will be slightly different between the docs, in-app onboarding, and wizard because they're displayed in different contexts. Some of these checkpoints could be API calls, prompts for the wizard, or instructions for the user to follow.


In an ideal world, we'd be able to use the wizard + these checkpoints to run E2E tests across all guides, allowing us to be proactive about guides that are out of date / broken.

It seems to me like that'd be a totally new way to do docs, that if we invested in writing E2E tests for docs then we wouldn't find ourselves in a situation where we find out things are broken because users tell us they are 🤔

Yeah @edwinyjlim has a separate RFC for this, basically

joshsny · 2025-09-08T19:21:21Z

requests-for-comments/2025-09-02-shared-instructions.md

+## Success criteria
+
+- Single source of truth to update getting started instructions for in-app onboarding, docs, and wizard.
+- The shared instructions should be stored in a **highly readable by humans** that's also easily parsable by machines.


+1 to we should be very careful to keep them human devex as good as it is now, as if we increase the friction for writing docs / guides as a result of this that would not be good.

Yes, that's how many of these projects I've been a part of fail.

joshsny · 2025-09-08T19:23:22Z

requests-for-comments/2025-09-02-shared-instructions.md

+## Option 1: Add the JavaScript snippet to your HTML Recommended
+"""
+
+# Indication of some custom component


Hmm I think this it too verbose for adding custom components - this feels good for adding verification steps / checks, but for all custom components it feels restrictive. Do we rely heavily on custom components in the docs at the moment?

I'd rather pass a component context in both the app / website as:

components={{"CalloutBox": <CalloutBox />}}

and then hide any missing components by default.

This has its problems since you are maintaining two sets of components, but you need to do that anyway with this being it's own step, right?

I am also slightly concerned about this one: How will we maintain type hinting etc. with a format like this? This way of using components seems like a step backwards. What if we change a component in posthog.com, and that breaks some of the components in use through the .toml files?

Great question. So it depends on how we want to parse/render this in docs/website. I wrote this in the spec in case if we want to parse the spec at run time.

We don't want to do live component imports. ReactMarkdown only supports the standard markdown set. MDX is very restrictive/dangerous to render at run time.

For example, we'd parse a component like:

case 'codeBlock': return ( <CodeBlock key={index} currentLanguage={{ language: item.language, code: item.code }}> {[{ language: item.language, code: item.code }]} </CodeBlock> )

And we'd enforce props used to exist, is of the proper format and time, and the rendering logic will be custom for each consumer (website/app)

If we pass a component context like components={{"CalloutBox": <CalloutBox />}}, we'd have to do some mdx manipulation for this to play well with the website 🤔 or we can template in these components at build time.

It depends on how we want to propagate updates. Not married to this format at all.

I think if we all agree to do this at build time as discussed below in the last section, we can totally just pass components into the mdx rendered.

This was mostly to dance around using mdx (like in the app. MDX feels... wrong to use in the app?)

joshsny · 2025-09-08T19:29:51Z

requests-for-comments/2025-09-02-shared-instructions.md

+Before proceeding, run `curl -X GET 'https://app.posthog.com/api/projects/{project_id}/events?event=test_event&after=2025-09-03T00:00:00Z' -H 'Authorization: Bearer {personal_api_key}'Retry`  
+"""
+
+# Show if event is received in app


I like this breakdown of steps, that's really nice

joshsny · 2025-09-08T19:32:03Z

requests-for-comments/2025-09-02-shared-instructions.md

+- During build by fetching/caching from `posthog/posthog.com/master`. Less manual, requires redeploy to update, could break/block people's builds. (This is how the website builds API docs right now.)
+- At run time. Always up to date. Could break without us knowing.
+
+I lean towards fetching and caching the latest known version in each repo and building the page from the reference material. We can minimize the chance of a bad change in docs breaking/blocking people's builds by enforcing reasonably strict linting.


+1 for this, PostHog/posthog get's enough changes for this to be a non-issue, and I can put something on Posthog/wizard to do a build and check for docs updates every day for example.

daniloc · 2025-09-08T20:22:07Z

requests-for-comments/2025-09-02-shared-instructions.md

+
+## Problem statement
+
+It's hard to maintain installation instructions in three different places.


daniloc · 2025-09-08T20:24:02Z

requests-for-comments/2025-09-02-shared-instructions.md

+
+It's also confusing when instructions are slightly different between the onboarding instructions and docs. We'd ideally like to see a user be able to jump between the two seamlessly.
+
+These instructions are now important for the new installation wizards owned by the growth team. The wizard should generally try to follow the instructions in the onboarding/docs, so that a user trying PostHog can jump between all three seamlessly.


It's also worth noting that when the wizard disagrees with docs, it breaks trust in the wizard, because AI, and it's a shame because we know that the wizard leaves more than 80% of people in great shape.

gewenyu99 and others added 5 commits September 2, 2025 20:23

init shared instruction rfc

025aa8d

Init draft

df2132c

better discussion

7aae37e

installation instructions

84a6487

Some tweaks

555c72b

joshsny reviewed Sep 8, 2025

View reviewed changes

daniloc reviewed Sep 8, 2025

View reviewed changes

gewenyu99 marked this pull request as ready for review September 10, 2025 19:47


		### Better troubleshooting workflow

		Another part of the problem is that only the in-app onboarding instructions have real-time feedback on if the user's on the right track. They do this by showing if a event has been received by PostHog.


		We can take this concept further by adding clear checkpoints and troubleshooting instructions to the wizard, docs, and in-app onboarding.

		These instructions will be slightly different between the docs, in-app onboarding, and wizard because they're displayed in different contexts. Some of these checkpoints could be API calls, prompts for the wizard, or instructions for the user to follow.


		## Problem statement

		It's hard to maintain installation instructions in three different places.


		It's also confusing when instructions are slightly different between the onboarding instructions and docs. We'd ideally like to see a user be able to jump between the two seamlessly.

		These instructions are now important for the new installation wizards owned by the growth team. The wizard should generally try to follow the instructions in the onboarding/docs, so that a user trying PostHog can jump between all three seamlessly.

Sharing instructions between docs, in-app onboarding, and wizard #362

Are you sure you want to change the base?

Sharing instructions between docs, in-app onboarding, and wizard #362

Uh oh!

Conversation

gewenyu99 commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joshsny left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonathanlab Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

gewenyu99 commented Sep 3, 2025 •

edited

Loading

jonathanlab Sep 9, 2025 •

edited

Loading