From 967a87b9728a1a306a09dc0d442db47a0f0d5bce Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Thu, 6 Mar 2025 16:26:08 +0100 Subject: [PATCH 1/6] create how to write quick start page --- docs/contributing/approach/sdk-docs/index.mdx | 8 +- .../sdk-docs/write-getting-started.mdx | 7 +- .../approach/sdk-docs/write-quick-start.mdx | 158 ++++++++++++++++++ 3 files changed, 170 insertions(+), 3 deletions(-) create mode 100644 docs/contributing/approach/sdk-docs/write-quick-start.mdx diff --git a/docs/contributing/approach/sdk-docs/index.mdx b/docs/contributing/approach/sdk-docs/index.mdx index 8fdbd153d25d9..a6bea0dc9030f 100644 --- a/docs/contributing/approach/sdk-docs/index.mdx +++ b/docs/contributing/approach/sdk-docs/index.mdx @@ -10,11 +10,15 @@ Our structure for SDK content focuses on getting a user up and running quickly, SDKs provide content that focus on 10 sections (two of which are auto-generated) that rely on common content. Each section is explained in detail on its own page. A quick overview: -1. **Getting Started** +1. **Quick Start / Getting Started (legacy)** A single, critical page. - **[How to Write - Getting Started](/contributing/approach/write-getting-started)** + For new SDKs and updated guides, use: + **[How to Write - Quick Start](/contributing/approach/write-quick-start)** + + To update existing Getting Started guides, use: + **[How to Write - Getting Started](/contributing/approach/write-getting-started)** This content is used in two different areas for Sentry customers: diff --git a/docs/contributing/approach/sdk-docs/write-getting-started.mdx b/docs/contributing/approach/sdk-docs/write-getting-started.mdx index 1d325203e0580..e39e25dee6f26 100644 --- a/docs/contributing/approach/sdk-docs/write-getting-started.mdx +++ b/docs/contributing/approach/sdk-docs/write-getting-started.mdx @@ -4,6 +4,12 @@ noindex: true sidebar_order: 30 --- + + This page describes the legacy "Getting Started" guide format. New SDKs and + guides that have been updated should use the [Quick Start guide + format](/contributing/approach/sdk-docs/write-quick-start/). + + A new platform/SDK should base it's Getting Started page of off a similar existing SDK page. Here's an overview of the general components of a Getting Started page. @@ -68,7 +74,6 @@ Add the verification code sample to this directory: - [`/src/platform-includes/getting-started-verify/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-verify) - ## But, that's not all The Getting Started content is also used by our in-app onboarding wizard to get customers up and running with Sentry. Keeping all content up to date is critical. diff --git a/docs/contributing/approach/sdk-docs/write-quick-start.mdx b/docs/contributing/approach/sdk-docs/write-quick-start.mdx new file mode 100644 index 0000000000000..42234f5454fe1 --- /dev/null +++ b/docs/contributing/approach/sdk-docs/write-quick-start.mdx @@ -0,0 +1,158 @@ +--- +title: How to Write - Quick Start +noindex: true +sidebar_order: 25 +--- + +We're transitioning from [Getting Started guides](/contributing/approach/sdk-docs/write-getting-started/) to Quick Start Guides. New SDKs should use the Quick Start guide format outlined on this page. This change is still in progress, so you may still encounter "Getting Started" guides in existing SDKs. + + + For existing Getting Started guides, refer to [How to Write - Getting + Started](/contributing/approach/sdk-docs/write-getting-started/). For example, + when you want to update a guide without changing it into a Quick Start guide. + If you're unsure what kind of guide you're looking at, ask a question by + opening an issue in GitHub. + + + +This change stems from our commitment to following best practices in documentation and making it easier for everyone to create and use our guides. + +With the new Quick Start guides, we want to provide a more structured and focused approach, helping writers create valuable content with confidence, ultimately assisting customers in reaching their goals with Sentry. + +**Quick Start vs. Getting Started:** +| | Quick Start | Getting Started | +| -------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| **Focus** | Goal-oriented, immediate action, minimal steps | Learning-oriented, broader concepts, background information | +| **Content** | Describes critical steps and doesn't explain much about how and why | More explanatory and provides background information | +| **Audience** | Developers who want to get started quickly | Developers seeking a deeper understanding | +| **Format** | Single page; Concise | Often spans multiple pages; Comprehensive | + + + +Our Quick Start guides aim to: + +- Enable developer to quickly set up Sentry with features such as Error Monitoring, Tracing, and Session Replay +- Keep instructions concise by avoiding unnecessary explanations or background information +- Focus on action by including code examples and commands +- Achieve a functional Sentry setup with visible results in a customer's Sentry project +- Serve as the basis for further customization + +## config.yml + +This file resides in the `/docs/platform//` directory. An example: + +```yaml +title: JavaScript +caseStyle: camelCase +supportLevel: production +sdk: "sentry.javascript.browser" +categories: + - browser +``` + +## Structure Templates + +We've created two Quick Start guide templates: one for wizard setup and one for manual setup. Use them as a basis and add new sections (steps) as you see fit. + +If an SDK has both Quick Start guides, make sure that both guides reach the same outcome, meaning the modifications in the customer's project should be consistent (within reason). + +### Wizard Setup + +The wizard is the fastest way to set up Sentry – your guide should reflect this by relying on the wizard for the core setup while providing additional information when it makes sense and helps the developer. You can wrap these additions into `Expandable` components to hide them by default and de-clutter your page visually. + +We recommend you base your guide on a similar existing SDK page, such as: + +- [Next.js quick start guide wizard setup](/platforms/javascript/guides/nextjs/) + +**Minimal structure:** + +- **Title and summary** + - The title gets picked up automatically from the config.yml file + - Describe what the developer will achieve by following this guide +- **Prerequisites** +- **Step 1: Install** + - Make sure "Install" is always the first step to get developers into action quickly + - Provide the primary installation method(s) for this SDK (we document alternate methods on a separate page, as in this [example](/platforms/javascript/install/)) + - Briefly introduce the features the wizard can enable; use an `Expandable` component to hide the content by default + - List the changes the wizard applies in the developer's application, such as updating configuration files and creating example code for testing the setup later; use an `Expandable` component to hide the content by default +- **Step 2: Verify Your Setup** + - Explain how to test the setup. For example, direct the developer to use the examples created by the wizard + - **Subsection: View Captured Data in Sentry** + - Direct developers to look at the captured errors in their Sentry project + - Optional: Provide detailed instructions using an `` +- **Next Steps** + - Wrap up and summarize what the developer achieved + - Provide a list of links to recommended next topics + +### Manual Setup + +Use this template for your manual setup guides. Keep your instructions concise and ask yourself, "Does the developer need to know this to successfully finish the guide, or is this a topic they can read about later in the documentation?" + +We recommend you base your guide on a similar existing SDK page, such as: + +- [Next.js quick start guide manual setup](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/) + +**Minimal structure:** + +- **Title and summary** + - The title gets picked up automatically from the config.yml file + - Describe what the developer will achieve by following this guide +- **Prerequisites** +- **Step 1: Install** + - Make sure "Install" is always the first step to get developers into action quickly + - Include onboarding options (feature setup) here before the installation instructions (use the [`OnboardingOption`](/contributing/pages/components/#onboarding-options) component) + - **Important**: Use the `OnboardingOption` component to toggle the visibility of feature-specific instructions in the guide. For example, if a developer wants to set up Tracing but not Session Replay, they should not get instructions on how to configure Session Replay. + - Briefly explain these features; use an `Expandable` component to hide the content by default + - Provide the primary installation method(s) for this SDK (we document alternate methods on a separate page, as in this [example](/platforms/javascript/install/)) +- **Step 2: Configure** + - Provide configuration examples and add comments in the code sample to limit the content you put into the surrounding prose + - Show how to configure Sentry and the selected features + - Use subsections for logical organization and splitting up long content +- **Step 3 - Step X: SDK-specific instructions** + - Create steps for source maps, tunneling, or other necessary instrumentation + - Each major topic should be a separate step +- **Step Y: Verify Your Setup** + - Provide verification code sample(s) for this SDK + - Adapt this section to the features of the selected onboarding option. For example, if Tracing is enabled, you need to describe how to verify it's set up correctly + - **Subsection: View Captured Data in Sentry** + - Direct developers to look at the captured errors in their Sentry project + - Optional: Provide detailed instructions using an `` +- **Next Steps** + - Wrap up and summarize what the developer achieved + - Provide a list of links to recommended next topics + +## Content Placement and Reusability + +If the content you want to include doesn't already exist, create a new file for your SDK in the respective folder in [`/src/platform-includes/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes). + +**Examples:** + +- **Install** [`/platform-includes/getting-started-install/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-install) +- **Configuration** [`/platform-includes/getting-started-config/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-config) +- **Verify** [`/src/platform-includes/getting-started-verify/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-verify) + +Integrate this content into your guide using the `PlatformSection` component. + + + If the SDK supports performance monitoring, add it to the list that links back + into the SDK content from Product, stored in + [`/docs/product/insights/getting-started.mdx`](https://github.com/getsentry/sentry-docs/blob/master/docs/product/insights/getting-started.mdx). + + +## Additional Requirements for Our Wizard + +The Quick Start content is also used by our in-app onboarding wizard to get customers up and running with Sentry. Keeping all content up to date is critical. + +Important: + +- If you update the code samples for an SDK, also update the wizard +- If you add something new, such as additional configuration, to the wizard also update the manual setup guide + +### Update the Wizard + +The in-app wizard is where customers first implement our SDKs. It's not a simple copy/paste from the Quick Start for two reasons: + +1. New customers lack the context that our Docs provide (think of it this way, there's no left-hand sidebar to review). +2. Experienced customers likely have alerts and so forth turned off, so don't expect one clear workflow. Also, don't review the workflow. Point customers to the product for a tour. + +As a result, a simple copy/paste of the Quick Start won't suffice. See the JavaScript wizard as an example. From 12297f4a2c66dce81d402143bc256f1abec7c8c3 Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Thu, 6 Mar 2025 16:52:18 +0100 Subject: [PATCH 2/6] fix broken link --- docs/contributing/approach/sdk-docs/write-getting-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/approach/sdk-docs/write-getting-started.mdx b/docs/contributing/approach/sdk-docs/write-getting-started.mdx index e39e25dee6f26..aaa320d71ebea 100644 --- a/docs/contributing/approach/sdk-docs/write-getting-started.mdx +++ b/docs/contributing/approach/sdk-docs/write-getting-started.mdx @@ -7,7 +7,7 @@ sidebar_order: 30 This page describes the legacy "Getting Started" guide format. New SDKs and guides that have been updated should use the [Quick Start guide - format](/contributing/approach/sdk-docs/write-quick-start/). + format](/contributing/approach/write-quick-start). A new platform/SDK should base it's Getting Started page of off a similar existing SDK page. From 7935787da32ba84f900eaff4aa97df1c5979f1df Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Mon, 10 Mar 2025 10:35:27 +0100 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Alex Krawiec --- docs/contributing/approach/sdk-docs/index.mdx | 2 +- .../approach/sdk-docs/write-quick-start.mdx | 19 +++++++++---------- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/contributing/approach/sdk-docs/index.mdx b/docs/contributing/approach/sdk-docs/index.mdx index a6bea0dc9030f..6cc10015a8f11 100644 --- a/docs/contributing/approach/sdk-docs/index.mdx +++ b/docs/contributing/approach/sdk-docs/index.mdx @@ -15,7 +15,7 @@ SDKs provide content that focus on 10 sections (two of which are auto-generated) A single, critical page. For new SDKs and updated guides, use: - **[How to Write - Quick Start](/contributing/approach/write-quick-start)** + **[How to Write - Quick Start](/contributing/approach/sdk-docs/write-quick-start/)** To update existing Getting Started guides, use: **[How to Write - Getting Started](/contributing/approach/write-getting-started)** diff --git a/docs/contributing/approach/sdk-docs/write-quick-start.mdx b/docs/contributing/approach/sdk-docs/write-quick-start.mdx index 42234f5454fe1..545e98097e1da 100644 --- a/docs/contributing/approach/sdk-docs/write-quick-start.mdx +++ b/docs/contributing/approach/sdk-docs/write-quick-start.mdx @@ -4,26 +4,25 @@ noindex: true sidebar_order: 25 --- -We're transitioning from [Getting Started guides](/contributing/approach/sdk-docs/write-getting-started/) to Quick Start Guides. New SDKs should use the Quick Start guide format outlined on this page. This change is still in progress, so you may still encounter "Getting Started" guides in existing SDKs. +We're transitioning from [Getting Started guides](/contributing/approach/sdk-docs/write-getting-started/) to Quick Start Guides. New SDKs should use the Quick Start guide format outlined on this page. This change is still in progress, so you may still encounter Getting Started guides for existing SDKs. - For existing Getting Started guides, refer to [How to Write - Getting - Started](/contributing/approach/sdk-docs/write-getting-started/). For example, - when you want to update a guide without changing it into a Quick Start guide. + If you want to update an existing Getting Started Guide without refactoring it into a Quick Start guide, see [How to Write - Getting + Started](/contributing/approach/sdk-docs/write-getting-started/). If you're unsure what kind of guide you're looking at, ask a question by - opening an issue in GitHub. + [opening an issue in GitHub](https://github.com/getsentry/sentry-docs/issues/new/choose). -This change stems from our commitment to following best practices in documentation and making it easier for everyone to create and use our guides. +This change stems from our commitment to following best practices and making our docs as accessible as possible. -With the new Quick Start guides, we want to provide a more structured and focused approach, helping writers create valuable content with confidence, ultimately assisting customers in reaching their goals with Sentry. +With the new Quick Start guides, we want to provide a more structured and focused approach, helping writers create valuable content with confidence, ultimately assisting users in reaching their goals with Sentry. **Quick Start vs. Getting Started:** | | Quick Start | Getting Started | | -------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | **Focus** | Goal-oriented, immediate action, minimal steps | Learning-oriented, broader concepts, background information | -| **Content** | Describes critical steps and doesn't explain much about how and why | More explanatory and provides background information | +| **Content** | Highlights critical steps with less focus on the how and why | More explanatory and provides background information | | **Audience** | Developers who want to get started quickly | Developers seeking a deeper understanding | | **Format** | Single page; Concise | Often spans multiple pages; Comprehensive | @@ -31,10 +30,10 @@ With the new Quick Start guides, we want to provide a more structured and focuse Our Quick Start guides aim to: -- Enable developer to quickly set up Sentry with features such as Error Monitoring, Tracing, and Session Replay +- Enable developers to quickly onboard Sentry with features such as Error Monitoring, Tracing, and Session Replay - Keep instructions concise by avoiding unnecessary explanations or background information - Focus on action by including code examples and commands -- Achieve a functional Sentry setup with visible results in a customer's Sentry project +- Achieve a functional Sentry setup with visible results in a user's Sentry project - Serve as the basis for further customization ## config.yml From 357b53b31a4e0e7a888c46d8198f68405dc342b6 Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Mon, 10 Mar 2025 10:51:26 +0100 Subject: [PATCH 4/6] feedback, update link --- .../sdk-docs/write-getting-started.mdx | 2 +- .../approach/sdk-docs/write-quick-start.mdx | 23 ++++++++++--------- 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/contributing/approach/sdk-docs/write-getting-started.mdx b/docs/contributing/approach/sdk-docs/write-getting-started.mdx index aaa320d71ebea..e39e25dee6f26 100644 --- a/docs/contributing/approach/sdk-docs/write-getting-started.mdx +++ b/docs/contributing/approach/sdk-docs/write-getting-started.mdx @@ -7,7 +7,7 @@ sidebar_order: 30 This page describes the legacy "Getting Started" guide format. New SDKs and guides that have been updated should use the [Quick Start guide - format](/contributing/approach/write-quick-start). + format](/contributing/approach/sdk-docs/write-quick-start/). A new platform/SDK should base it's Getting Started page of off a similar existing SDK page. diff --git a/docs/contributing/approach/sdk-docs/write-quick-start.mdx b/docs/contributing/approach/sdk-docs/write-quick-start.mdx index 545e98097e1da..69631c0b29c55 100644 --- a/docs/contributing/approach/sdk-docs/write-quick-start.mdx +++ b/docs/contributing/approach/sdk-docs/write-quick-start.mdx @@ -7,10 +7,11 @@ sidebar_order: 25 We're transitioning from [Getting Started guides](/contributing/approach/sdk-docs/write-getting-started/) to Quick Start Guides. New SDKs should use the Quick Start guide format outlined on this page. This change is still in progress, so you may still encounter Getting Started guides for existing SDKs. - If you want to update an existing Getting Started Guide without refactoring it into a Quick Start guide, see [How to Write - Getting - Started](/contributing/approach/sdk-docs/write-getting-started/). - If you're unsure what kind of guide you're looking at, ask a question by - [opening an issue in GitHub](https://github.com/getsentry/sentry-docs/issues/new/choose). + If you want to update an existing Getting Started Guide without refactoring it + into a Quick Start guide, see [How to Write - Getting + Started](/contributing/approach/sdk-docs/write-getting-started/). If you're + unsure what kind of guide you're looking at, ask a question by [opening an + issue in GitHub](https://github.com/getsentry/sentry-docs/issues/new/choose). @@ -36,9 +37,9 @@ Our Quick Start guides aim to: - Achieve a functional Sentry setup with visible results in a user's Sentry project - Serve as the basis for further customization -## config.yml +## Structuring the config.yml File -This file resides in the `/docs/platform//` directory. An example: +The config.yml file provides SDK-level details, such as its title, support level, and device categories. This file resides in the `/docs/platform//` directory. An example: ```yaml title: JavaScript @@ -53,7 +54,7 @@ categories: We've created two Quick Start guide templates: one for wizard setup and one for manual setup. Use them as a basis and add new sections (steps) as you see fit. -If an SDK has both Quick Start guides, make sure that both guides reach the same outcome, meaning the modifications in the customer's project should be consistent (within reason). +If an SDK has both Quick Start guides, make sure that both guides reach the same outcome, meaning the modifications in the developer's project should be consistent (within reason). ### Wizard Setup @@ -140,7 +141,7 @@ Integrate this content into your guide using the `PlatformSection` component. ## Additional Requirements for Our Wizard -The Quick Start content is also used by our in-app onboarding wizard to get customers up and running with Sentry. Keeping all content up to date is critical. +The Quick Start content is also used by our in-app onboarding wizard to get users up and running with Sentry. Keeping all content up to date is critical. Important: @@ -149,9 +150,9 @@ Important: ### Update the Wizard -The in-app wizard is where customers first implement our SDKs. It's not a simple copy/paste from the Quick Start for two reasons: +The in-app wizard is where developers first implement our SDKs. It's not a simple copy/paste from the Quick Start for two reasons: -1. New customers lack the context that our Docs provide (think of it this way, there's no left-hand sidebar to review). -2. Experienced customers likely have alerts and so forth turned off, so don't expect one clear workflow. Also, don't review the workflow. Point customers to the product for a tour. +1. New users lack the context that our Docs provide (think of it this way, there's no left-hand sidebar to review). +2. Experienced users likely have alerts and so forth turned off, so don't expect one clear workflow. Also, don't review the workflow. Point users to the product for a tour. As a result, a simple copy/paste of the Quick Start won't suffice. See the JavaScript wizard as an example. From ba189ea31b27889268d74efaa566eb0e230854e9 Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Thu, 13 Mar 2025 09:36:03 +0100 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Charly Gomez --- docs/contributing/approach/sdk-docs/write-quick-start.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/approach/sdk-docs/write-quick-start.mdx b/docs/contributing/approach/sdk-docs/write-quick-start.mdx index 69631c0b29c55..f63d9f7f5e62c 100644 --- a/docs/contributing/approach/sdk-docs/write-quick-start.mdx +++ b/docs/contributing/approach/sdk-docs/write-quick-start.mdx @@ -4,7 +4,7 @@ noindex: true sidebar_order: 25 --- -We're transitioning from [Getting Started guides](/contributing/approach/sdk-docs/write-getting-started/) to Quick Start Guides. New SDKs should use the Quick Start guide format outlined on this page. This change is still in progress, so you may still encounter Getting Started guides for existing SDKs. +New SDKs should use the Quick Start guide format outlined on this page. You may still encounter Getting Started guides for existing SDKs. If you want to update an existing Getting Started Guide without refactoring it @@ -150,7 +150,7 @@ Important: ### Update the Wizard -The in-app wizard is where developers first implement our SDKs. It's not a simple copy/paste from the Quick Start for two reasons: +The in-app wizard is where developers first integrate our SDKs. It's not a simple copy/paste from the Quick Start for two reasons: 1. New users lack the context that our Docs provide (think of it this way, there's no left-hand sidebar to review). 2. Experienced users likely have alerts and so forth turned off, so don't expect one clear workflow. Also, don't review the workflow. Point users to the product for a tour. From 2755cbf5277c0396ca2d6081f82920dd0c31c5da Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Thu, 13 Mar 2025 09:39:27 +0100 Subject: [PATCH 6/6] link to next.js wizard --- docs/contributing/approach/sdk-docs/write-quick-start.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/approach/sdk-docs/write-quick-start.mdx b/docs/contributing/approach/sdk-docs/write-quick-start.mdx index f63d9f7f5e62c..80e1b919e267a 100644 --- a/docs/contributing/approach/sdk-docs/write-quick-start.mdx +++ b/docs/contributing/approach/sdk-docs/write-quick-start.mdx @@ -155,4 +155,4 @@ The in-app wizard is where developers first integrate our SDKs. It's not a simpl 1. New users lack the context that our Docs provide (think of it this way, there's no left-hand sidebar to review). 2. Experienced users likely have alerts and so forth turned off, so don't expect one clear workflow. Also, don't review the workflow. Point users to the product for a tour. -As a result, a simple copy/paste of the Quick Start won't suffice. See the JavaScript wizard as an example. +As a result, a simple copy/paste of the Quick Start won't suffice. See the [Next.js wizard](https://github.com/getsentry/sentry-wizard/tree/master/src/nextjs) as an example.