Documentation / learning architecture

[smallbrownbike]

A recent issue sparked some ideas about how we should be structuring some informational content on the site—opening this issue to start the conversation and provide my initial thoughts.

First, I think it would be immensely helpful in getting users to dive in quickly if we had a simple “getting started” page as the root. I’m thinking it contains just the basic steps in setting up PostHog:

• Step 1. Pick your hosting option

  • Should list options and why you should choose one over the other
  • Maybe this part can be interactive and quiz-like?

• Step 2. Deploy and come back here when you’re done

  • Should list options and link to doc instructions for each
  • We have a sweet deploy options component with pretty icons we can throw in here

• Step 3. Learn

  • List great starter tutorials for a beginner
  • Add a “more” button that links to a page dedicated to learning content
  • Add a button that links to the technical docs for people that already know what they want to do

Learning page

The learning page can contain all of the tutorials/how-to guides. We should separate tutorials and how-to guides with different wording to reduce confusion between the two. For instance, the tutorials section of the page can be written as “Using PostHog”, while the how-to section can be written as “Do fun things with PostHog” (yes, that is a terrible title).

• Under each section, there should be a list of posts sorted in a meaningful way. Perhaps the tutorials can be listed in steps, and the how-tos can be listed by read-time/difficulty.

• Each section should contain a link to its respective listing page where all of the content for that type will live. (/tutorials, /how-to-guides)

  • Individual listing pages should have the ability to filter. Maybe by category/tag, read-time/difficulty.

[leggetter]

TL;DR - as I've now written this out, I think there's a lot to consider here. There are a couple of quick wins such as an update of /docs and a getting started page. The overall information architecture, however, is something that requires a lot of thought).

First, I think it would be immensely helpful in getting users to dive in quickly if we had a simple “getting started” page as the root

Do you mean for /docs?

I don't think this would work as the root has to cater for different types of users. For example, users at different stages for their journey with PostHog such as those that have already deployed. However, I do agree that a section dedicated to getting started would be a big improvement.

I also agree that the /docs landing page could be more of a landing page that helps the user more quickly find the contents they're looking for. Something that combines listing products/features with quick links into key content, with listing content types to help with a more explorative usage of the docs.

To summarise: at the top-level of this broader discussion I think there are a few things:

1. A re-imagining of what /docs may be
2. The need for a getting started journey
3. Larger information architecture review

We need to remember that we live at the intersection of end-user and developer so getting the balance right here is important. I'd previously thought we should separate the journey for these different users (or the same user within a different mindset) but it's very hard to remove the need for an element of coding to make use of our product. So, my current thinking is that it'd be better to embrace that.

Something that could help with all of this is some examples of third-parties that we feel have done a good job. And probably some bad examples too 🙂

A few links to get us started:

• https://stripe.com/docs - although considered developer-focused there's more and more docs that enable non-developers such as https://stripe.com/docs/invoicing/dashboard
• Slack: they really separate the journey as I'm sure they have far more non-devs that devs:
  • Docs is a help side https://slack.com/intl/en-gb/help/categories/200111606-Using-Slack
  • API docs has a dedicated destination https://api.slack.com/
• https://docs.mattermost.com/ - probably a good reference as an open-source and extensible product.
• https://docs.launchdarkly.com/home (developer-focused)
• https://www.twilio.com/docs (developer-focused)