Ask A BotHow to Write - Getting Started
In most cases, the platform/SDK will adopt the common index page, which is stored in src/platforms/common/, as the index.mdx file - feel free to peruse that file to answer any questions.
DO NOT change the common content. That change will ripple across all SDKs that rely on the common content. Instead, open an issue on GitHub with questions/suggestions.
If the SDK doesn't suit this content approach, then maintain the index.mdx file for that SDK.
Otherwise, build the components that are described in the following sections.
config.yml
This file resides in the /platform/<SDK_name>/ directory. An example:
title: JavaScript
caseStyle: camelCase
supportLevel: production
sdk: "sentry.javascript.browser"
categories:
- browserPrimer Content
Explain the SDK at a high level in these two parts:
An italicized sentence that explains what the SDK enables (errors, or errors and transactions)
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 /src/docs/product/performance/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 used by both our in-app wizard and our marketing site to get customers up and running with Sentry. Keeping those sources up to date is critical.
If updating the code samples for an SDK, also update the Wizard and check the marketing site.
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:
- New customers lack the context that our Docs provide (think of it this way, there's no lefthand sidebar to review).
- 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.
Audit the Marketing Site
The marketing site uses the Getting Started code samples as well. The code samples and instructional text display here:
sentry.io/for/<sdk_name>/
If anything is incorrect or requires updating, let us know by opening an issue on GitHub.
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").