Spruce up tutorials section

[corywatilo]

We have some great tutorials, but I feel like they could look a little more compelling and feel less associated with Docs and more part of the website (and used to sell PostHog).

Design to-dos

• [x] Create a tutorials index view (grid view maybe?)
• [x] Add a block for author details (especially useful for encouraging contributed tutorials!)
• [x] Anchor links menu feel sort of bleh in tutorials
• [x] Concept of categories, which would also mean we use blog/handbook/docs subheader
• [x] Component for large images (eg: <ExpandedImage zoom=true where it expands outside the content width, and maybe you can zoom to use your whole screen)

Open questions

• Should Tutorials continue to live in the Docs template, or should we break it out into its own section without the chapter (left) menu? (I'm leaning yes.)

Edit: This is essentially what we call a blog

[leggetter]

I plan for us to create more of these types of tutorial https://deploy-preview-2225--posthog.netlify.app/docs/tutorials/supabase-nextjs-signup-funnel

So would appreciate that being taken into account when doing the sprucing 🌲

❤️ the author details. Can we support multiple authors?

Stretch requests:

• Utilize tags to show related tutorials under other tutorials and also under other documentation content. For example, https://posthog.com/docs/tutorials/spa is JavaScript related so should appear under https://posthog.com/docs/integrate/client/js. There are also User Guides that should link through to tutorials. This will require a bit of investigation but I feel it'll be valuable.
• +1 for the grid view but also use the tags to allow you to filter the content

[joethreepwood]

Bringing it into the issue from a Slack conversation because I think it would shape the content in this section: I think we need to consider the overall architecture of docs.

Right now we have:

• Docs: Technical documentation specifically for engineers and unsuitable for non-technical audiences. The Docs category contains sections about deployment, integration, APIs and contribution. Docs also contains the following two categories.
• User Guides: Feature-led content that fits with a ‘What does X button do?’ structure, currently encompassing Funnels, Paths, etc. It’s suitable for non-technical users.
• Tutorials: This is our most underdeveloped section and fits with a 'How do I do X?' structure. AARRR funnels, conversion, etc.

@jamesefhawkins and I were discussing on Slack and hit on the fact that Tutorials and User Guides should probably be the same thing, so that we move towards:

• Docs: Documentation about what features do at a base-level, encompassing the existing technical areas (deployment, integration, etc.) as well as the non-technical feature-led content (funnels, paths, etc.).
• User Guides / Tutorials: Documentation about how to accomplish specific tasks after deployment. AARRR funnels, conversions, etc.

In short, having three categories (two of which have similar names and which are nested in a larger category) is obscuring content.

[leggetter]

I've had a bit of time to think about this and How-to guides are different from tutorials so we should not combine the content. However, we should review and make sure the content is in the correct place.

This table of the characteristics of documentation and the associated write-up should clarify why better than I can here.

It doesn't give us a step-by-step guide of what we should do with our content (now or in the future). We'll need to do some more analysis, write up our "how we structure our docs" (see how the Django docs are structured), and then do a reorg. As such, I'd recommend we:

1. Keep this issue focused on sprucing up tutorials
2. Create another issue for reviewing the content of our existing docs and blog posts, and making sure things are correctly in User Guides (Explanation -> How to) or Tutorials
3. (If we feel it's a priority) Create an Epic for a larger docs information architecture review which should work hand-in-hand with the PostHog app IA updates. But we'll either need to reprioritise other things to do this work or wait for the DevEd hire. Or, we agree this is going to be a big ongoing concern with a lot of upfront work and hire a Technical Writer who lives and breaths this sort of thing.

[joethreepwood]

I've had a bit of time to think about this and How-to guides are different from tutorials so we should not combine the content. However, we should review and make sure the content is in the correct place.

Based on this chart, surely what we call User Guides would still fit mostly under Reference/Explanation?

[leggetter]

Based on this chart, surely what we call User Guides would still fit mostly under Reference/Explanation?

It differs between each piece of content. For example, Actions is mainly Explanation, Annotations is Explanation followed by How-to, SSO is How-to.

As I mentioned, I think analysing and resolving this is a reasonable piece of work that should sit outside of sprucing up the tutorial design.

[smallbrownbike]

I agree that tutorials and how-to guides are different from each other, but I think categorizing them with that wording might be confusing to users. I have a solution to that here where we can talk about the documentation architecture in general.

[leggetter]

Another example of how tags could be useful:

For https://posthog.com/docs/user-guides/funnels it'd be great to auto-link to the three tutorials we have on funnels:

• https://posthog.com/docs/tutorials/funnels
• Next.js, Supabase + Funnels (deploying)
• AAARR (in PR)

[corywatilo]

Tutorials v2 [Website as a Product edition]

Continuing the line of thinking about the website as a product (private url), here's a Tutorials flow that combines a few concepts:

1. Persistent left-nav throughout the website - feels more like an interface than a marketing site trying to sell you something)
2. Sub nav column (contextual)
3. Combines text-based and video tutorials (when available)
4. Global content tagging/linking system

Things you should do in this prototype:

1. Important: _First, at top right in Figma, click Options > Uncheck Show Figma UI so you can see the top bar_
2. In list view, toggle between Feed view and List view
3. Click the first tutorial
4. Scroll the tutorial to see which elements are locked in place
5. Switch to the Video tab
6. Click the Magic button at the top to see related content from other parts of the site!

Key screenshots

Persistent nav, Filtering column, Feed view

Tutorial article meta info, sharing, tags, video tab

Magic mode, showing related content from all parts of our site

Key topics would be rolled up to site-level tags (eg: each major feature, etc)

MVP

To get a version of this out, we can reduce a lot of scope and just start with a feed and a filter sidebar and break Tutorials and User Guides out of Docs. (We can carry this sidebar across Blog, Tutorials, User guides as a first step.)