How to Write - Quick Start

We're transitioning from Getting Started guides 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.

Why the change?

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

This file resides in the /docs/platform/<SDK_name>/ directory. An example:

Copied
title: JavaScript
caseStyle: camelCase
supportLevel: production
sdk: "sentry.javascript.browser"
categories:
  - browser

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).

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:

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)
    • 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 <Expandable>
  • Next Steps
    • Wrap up and summarize what the developer achieved
    • Provide a list of links to recommended next topics

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:

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 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)
  • 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 <Expandable>
  • Next Steps
    • Wrap up and summarize what the developer achieved
    • Provide a list of links to recommended next topics

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/.

Examples:

Integrate this content into your guide using the PlatformSection component.

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

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.

Previous
Common Content
Next
How to Write - Getting Started
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").