Sentry uses a minimalist approach to documentation. Our docs have one goal: help customers gain mastery quickly. Minimalism in documentation puts the reader at the center of the content. Our audience is reading the documentation to solve a problem or finalize a setup or to understand. Thus, think very critically about the content that is provided, especially on a primary page.
Use This Test
Ask these questions as you're developing content:
Is this information critical to helping a developer get up and running? If not, consider moving it to a subpage with a link to it from the primary page (or, as suggested by one of our engineering managers, "cool, I can bookmark this for later").
Is this obvious from the UI? Our UI is largely self-documenting, so we don't need to explain what's already evident.
What Goes Where?
Our content has some pretty clear divisions:
- Platform/SDK content - instrument and configure your SDK
- Product content - look at all the data ingested into Sentry
And within those primary categories:
- Reference: What customers need to know
- Action: What customers can do (modify, filter, and so forth)
If you're uncertain, ask.
Writing for Sentry
Keep these concepts in mind when contributing to docs:
- Technical accuracy is our primary consideration. Our content helps every developer diagnose, fix, and optimize their code.
- Use inclusive language, which we discuss more fully here.
- Feedback is a gift - share your PR so we can improve our content.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").