Closed corywatilo closed 2 years ago
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:
tags
to allow you to filter the contentBringing 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:
@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:
In short, having three categories (two of which have similar names and which are nested in a larger category) is obscuring content.
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:
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?
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.
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.
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:
Continuing the line of thinking about the website as a product (private url), here's a Tutorials flow that combines a few concepts:
Things you should do in this prototype:
Key topics would be rolled up to site-level tags (eg: each major feature, etc)
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.)
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
<ExpandedImage zoom=true
where it expands outside the content width, and maybe you can zoom to use your whole screen)Open questions
Edit: This is essentially what we call a blog