Update documentation information architecture (IA) to improve activation

[leggetter]

Context

Identify some short-time wins that help us nail funnels by improving activation through improving the PostHog documentation experience and content.

Goals

• Improve manual discoverability (navigation) of documentation content through restructuring the information architecture.
• Identify any gaps in documentation

Ways we could structure the Information Architecture (IA)

• Content type e.g. Getting Started, Guides, Tutorials, Reference
• Goal oriented - by what a user is trying to achieve; where they are in their product usage lifecycle e.g. Deployment/Installation, Configuration, Integration, User Guides
• By product. This assumes that we break PostHog up into individual products such as Insights, Session Recording, and Feature Flags. Then, the top-level item in the IA is the product and then sub sections are broken down by either type or what the user is trying to achieve.
  • Product -> Goal
  • Product -> Content Type

Key factors

• Cloud vs. Self-Hosted: Deployment/installation and configuration (? - requires full content review) focused content is only relevant to those that are self-hosting.
• Customer lifecycle and the user type: to begin with the customer is installing and integrating. They then move to using PostHog e.g. creating funnels. Each step in the customer lifecycle requires different documentation.

Examples of other products and projects/companies that have these same considerations:

• Django CMS: https://docs.django-cms.org/en/latest/
• Mattermost: https://docs.mattermost.com/

Suggested Information Architecture (IA)

Since we’re looking for short-term wins and we have some resource constraints, the recommendation is to move to keep our goal-orientated IA with some reorganization and renaming of the contents to make the contents easier to navigate and naturally find the content we have.

In particular, a section focused on using the PostHog application (Using PostHog) will be introduced that will bring in the Features and Platform Structure sections. This should provide customers with a clear destination in that phase of their journey with PostHog.

Top-Level

The goal of the top-level IA is to map to the journey the customer takes with PostHog. This will differ slightly depending on if they choose self-hosted or cloud:

Self-Hosting

1. Begin by Deploying PostHog
2. Next, Configuring PostHog
3. Then, Integrating PostHog into a web or mobile application stack, even if it’s just a test event
4. At this point there may be a requirement to front-load some data via the API or extend functionality via Plugins

Cloud

1. Cloud customers begin with Integrating
2. They then move on to Using PostHog
3. As with self-hosting customers, at this point there may be a requirement to front-load some data via the API or extend functionality via Plugins

Top-Level IA

Existing	New
Tutorials Deployment Configuring PostHog Libraries Features Plugins API Contributing Platform Structure	Deploy Configure Integrate User Guides Plugins Tutorials Contribute API

More detail and collaborative feedback

A detailed breakdown of the IA can be found in the following Google document that has comments enabled for everyone:

📝 https://docs.google.com/document/d/1gO6gY8FAuOkiIAADaDbThW2FN3UzVWzOH67-HLYLdgk/edit#heading=h.38e6a6jy0xd0

It should be much easier to collaborate on the IA structure in the Google doc.

Tasks

• [x] Get feedback and update plan: IA (Information Architecture) and content gaps
• [ ] Restructure contents
• [ ] Review and update /docs/updating-documentation as required to reflect updated IA. Add section/page on IA.
• [ ] Update main /docs page to reflect new structure
• [ ] Create separate issue for identified content gaps

[macobo]

Fly-by comment: It's worth keeping API documentation on top level. When people need it (our existing material is not enough) they should not look for it nested.