SDK Documentation Structure
Our structure for SDK content focuses on getting a user up and running quickly, then learning about all the features that can be configured or enabled in subpages. These subpages provide reference material, with code examples specific to the SDK.
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:
Getting Started
A single, critical page.
How to Write - Getting Started
This content is used in two different areas for Sentry customers:
- docs.sentry.io
- In-app wizard for customers creating or adding a project
Configuration
Covers all the ways customers can manage their implementation of the SDK. It consists of subpages (all of which can be turned on or off, as appropriate to the SDK).
Usage
Covers how to capture errors and messages, with a subpage to set the Level.
Troubleshooting
Covers corner and edge cases we know of. This content is developed at the primary SDK level, so is shared by the primary SDK and its associated guides. It is not common to all SDKs/platforms.
The content resides in this directory
/docs/platforms/<SDK>/common/troubleshooting/(Optional) Migration Guide
Provided for customers who need to upgrade from the Raven version of the SDK. Not needed for newer SDKs.
Tracing section
Covers how to enable tracing (for customers who previously only used error monitoring) as enabled by each SDK, as well as subpages on Sampling and Transactions.
This section is a WIP.
Enriching Events section
Covers the data sent to Sentry, as well as how to customize it.
Data Management section
Covers our algorithm for grouping and how it can be modified, as well as how to scrub sensitive data using the SDK.
(Auto-generated) Other Guides
Lists the other related platforms/integrations/SDKs for this SDK.
(Auto-generated) Other Platforms
Lists the other primary SDK/platforms.
This model is quite flexible - some SDKs will incorporate more information- others will require less information.
We have several goals to using this format:
- Ensure customers have a single page that gets them started quickly.
- Update the SDK content so that it is both technically accurate and complete.
- Ensure we've architected to support the structure of our docs, which separates Platform/SDK content from Product content. Think of this as "Platform/SDK docs help a customer send data to Sentry" and "Product docs help a customer understand what's in sentry.io, then determine an appropriate response"
- Read the contributor guidelines. The guidelines will help you set up your docs environment (the move to our new tooling is significant) and provide key technical details about SDK content, search, redirects, and the Wizard pages. If you need help, ask for help by opening an issue in GitHub.
- Use the "How to" pages to understand what content is covered where.
- Use the files and folder structure in JavaScript as a model.
- Create a PR and please request getsentry/docs as reviewers.
- Wonder and ponder. The model is not meant to work 100% of the time. It's anticipated that some of the content won't work neatly. If you're not sure where content should display, ask a question by opening an issue in GitHub.
- Don't forget to update the Wizard Pages that use the Getting Started content to help direct customers on sentry.io
- Don't forget to update the listing of SDKs that support performance monitoring, as appropriate.
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").