Skip to content

Latest commit

 

History

History
90 lines (54 loc) · 3.57 KB

write-getting-started.mdx

File metadata and controls

90 lines (54 loc) · 3.57 KB
title noindex sidebar_order
How to Write - Getting Started
true
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.

config.yml

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

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

Primer Content

Explain the SDK at a high level in these two parts:

  1. An italicized sentence that explains what the SDK enables (errors, or errors and transactions)

  2. A brief paragraph that provides technical insight and the versions supported

    If the primer content isn't developed, this fallback will display "Sentry's SDKs enable automatic reporting of errors and exceptions."

Add the primer content to this directory:

Installation Method

Provide an example of the primary installation method for this SDK. While we document alternate methods, we keep those on a separate page (as in this example) to keep the focus of the Getting Started content on the most-common, fastest way to get up and running.

Add the installation method to this directory:

Configuration Code Sample

Provide an example of the configuration of this SDK, commenting in the code sample, not the surrounding prose.

Add the configuration code sample to this directory:

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.

Verification Code Sample

Provide a verification code sample for this SDK. It can be as simple as one line, though the SDK may require a more complex code sample.

Add the verification code sample to this directory:

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.

If updating the code samples for an SDK, also update the Wizard.

Update the Wizard

The in-app wizard is where customers first implement our SDKs. It's not a simple copy/paste from the Getting Started for two reasons:

  1. New customers lack the context that our Docs provide (think of it this way, there's no lefthand 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 Getting Started won't suffice. See the JavaScript wizard as an example.