Considerations: Quick start, getting started, how-to

[inventarSarah]

SDK

All JavaScript SDKs

Description

Below, you can find some details about Quick Start Guides and Getting Started Guides, which will help get a clearer picture of what's what. Following our discussion, I also had some thoughts about How-to guides, which you can read about at the end.

Let me know if you have any questions about this -- otherwise, I guess we'll chat about the topic again during our next weekly.
Thanks!

Quick Start Guide

Focus:

• Goal-oriented content
• What are the minimal steps the user needs to take to get up and running -> best with visible results

Content:

• Describes only the critical steps and configs (e.g., install, configure, verify)
• Usually does not explain much about how and why

Audience:

• Users who want to get going quickly, experiment on their own, and come back to learn as they encounter challenges
• Users who want quick results, e.g., to compare different providers
• Experienced users who want to use a different Sentry SDK

Format:

• One page should suffice
• step-by-step instructions, screenshots, videos
• Brief + Simple

--> I think this is more or less what we currently have in Getting Started

Getting Started Guide

Focus:

• Learning-oriented content
• Helps the user get a foundational understanding of how to use Sentry (SDK); What does the average user need to know to get the most out of Sentry

Content:

• Includes more detailed descriptions, instructions, and examples
• Provides background information
• Provides links to further reading
  • for example, tunneling > explain and show the basics and then link to detail page with more information

Audience

• Provides a more supporting learning curve for users who want guidance
• Great for new users who have no clue about most things yet

Format:

• Typically spans across multiple pages where each page covers one topic
• instructions, examples, tips, links to other sections of docs
• Clear and Complete

Examples

• Gatsby
  • Quick Start
  • Getting Started
• GitHub API
  • Quick Start
  • Getting Started
• Storyblok
  • Quick start Next.js
  • Getting Started Next.js

How-to Guides

During our chat, I got the impression that we sometimes wonder where to put information about specific use cases or questions.
Since I'll try to set up Sentry in a PHP React app soon, I've been thinking about how to do that and already have questions I don't know where to find in the documentation.
Based on these two observations, I also want to propose the following and see if you think this could also be helpful (or what the results of previous discussions on this topic were):

Since users' tech stacks & setups are diverse, it is probably impossible to provide all the answers, information, and support needed in the docs in a convenient, easily accessible way. Instead, users have to navigate different pages and pick up bits of knowledge from here and there, trying to complete their puzzle (which is tedious and may not lead to the desired result since they can easily miss things).

Trying to put everything into the documentation isn't the best approach -- it would overcomplicate and clutter the documentation.

A good solution is providing how-to guides (text and/or video) outside of the more "rigid" documentation structure.
How can I set up Sentry in my Laravel React app? -> Guide
How can I set up tracing for my xyz project? -> Guide

Of course, these how-to guides need to be connected to the Documentation where the user can find deeper insights; Cross-linking is always a good idea

I know we already have tutorials and videos, but they are very tricky to find. Having a dedicated Blog/Guide/Tutorial hub for Developers would be super useful (this could still be accessible from the Documentation, for example).
Some examples:

• Storyblok is a great example -- they have tons of tutorials, and you can filter by technology, which helps a lot to remove "the noise"
• Docker does something similar with their Guides

Suggested Solution

No response

[smeubank]

generally i like the way the example sites have quick start and getting started. I am very hesitant (maybe brainwashed 🙃 ) to move away from our quick start style guides. but now I think the solution is maybe closer, to treathing them more like quick starts purely, and that getting starteds docs are a different problem and different tool, to compliment the other

I know we already have tutorials and videos, but they are very tricky to find. Having a dedicated Blog/Guide/Tutorial hub for Developers would be super useful (this could still be accessible from the Documentation, for example).

i like this idea, there could even simply be cards similar to the storyblok example which link to the existing youtube videos. https://www.youtube.com/@Sentry-monitoring/videos, could just pull a subset of them, potentiall add some tags to them, so they could be filtered and searched more easily, similar to the changelog. Just a cards, with meta preview, title, description, and tags behind in some json

[mydea]

This all generally sounds very good to me, I like this splitting of Quick Start vs. Getting Started, and it is indeed something that you often find in other docs as well!

Of course, these how-to guides need to be connected to the Documentation where the user can find deeper insights; Cross-linking is always a good idea

We have kind of tried to solve this (partially) in "Special Use Cases" like this: https://docs.sentry.io/platforms/javascript/best-practices/ but it has been a point of contention how to call this, what to put into it etc. So this is def. also something we can reshuffle/rethink!

[inventarSarah]

I agree, I wouldn't do away with quick start guides either -- they are very useful. Defining a clear purpose and focus for these guides will be helpful for anyone writing, maintaining and reviewing one. For example, it will make it easier to decide what information should appear in a Quick Start and whats already too much or too in-depth.
I may have more thoughts on this after I set up Sentry in a php react app :) (will try this today)