technical-docs

---
name: technical-docs
description: Write and review technical documentation for Sentry SDK docs. Use when creating, editing, or reviewing documentation pages, especially MDX files in docs/platforms/.
---

# Technical Documentation Writing

## Core Principles

### 1. Lead with "Why", Then "How"

Every section must answer: **Why would a developer need this?**

Bad:
```
## Server Actions
Use `captureException` in Server Actions to report errors.
```

Good:
```
## Server Actions
Server Actions that return error states to the client catch errors before Sentry sees them.
Report these manually so you don't lose visibility.
```

### 2. Structure by User Intent, Not API Surface

Organize around what developers are trying to do, not around API methods.

Bad structure (API-centric):
- captureException
- captureMessage
- withScope

Good structure (intent-centric):
- Errors that need manual capture (and why)
- Adding context to errors
- Troubleshooting missing errors

### 3. Avoid Redundant Examples

If the same pattern appears in multiple sections, consolidate it.

**Ask yourself:** "Am I showing the same code pattern again? If yes, reference the earlier example instead."

Bad:
```
## Error Boundaries
Sentry.captureException(error);

## Server Actions
Sentry.captureException(error);

## API Routes
Sentry.captureException(error);
```

Good:
```
## Where Manual Capture is Needed

These Next.js patterns catch errors before Sentry sees them:
- Error boundaries (error.tsx files)
- Server Actions returning error states
- API routes with custom error responses

[Single example with explanation of the pattern]
```

### 4. Be Precise About When/Why

Don't just show code. Explain the specific condition that requires this approach.

Bad:
```
Add captureException to report these errors.
```

Good:
```
Next.js error boundaries intercept errors before they bubble up to Sentry's global handler.
Without manual capture here, these errors silently disappear from your Sentry dashboard.
```

### 5. Concise for Humans, Complete for Context

Write clearly and concisely. Long pages with repeated patterns lose readers.

- Keep explanatory text short and direct
- One code example per concept (not per location)
- Use TL;DR summaries for long sections
- Prefer bullet points over prose for lists

### 6. Best Practices as Guidance, Not Repetition

Best practices should add new information, not repeat earlier examples.

Bad best practice:
```
## Best Practices
### Use captureException in Error Boundaries
[same code shown earlier]
```

Good best practice:
```
## Quick Reference
- Error boundaries: Required for visibility (errors intercepted by Next.js)
- Server errors: Automatic unless you return custom responses
- Client errors: Automatic for unhandled exceptions
```

## Sentry Docs Specific Patterns

### PlatformLink Usage

Link to related docs rather than repeating content:
```
For automatic tracing, see <PlatformLink to="/configuration/apis/">API Reference</PlatformLink>.
```

### Code Block Meta Flags

Always include filename when showing file-specific code:
```tsx {filename:app/error.tsx}
```

Consecutive fenced code blocks are automatically grouped into tabbed code snippets.
Each tab can have a title and filename:

~~~
```swift {tabTitle:Swift}
SentrySDK.capture(error: error)
```

```objc {tabTitle:Objective-C}
[SentrySDK captureError:error];
```
~~~

#### Markdown Export and `{mdExpandTabs}`

The `.md` export (mainly used by LLMs via the "Copy page" button) **collapses tab groups
by default**: only the first tab is included, with a note listing the other tabs
(e.g. *Other available variations of the above snippet: yarn, pnpm*). This keeps context lean when tabs show
trivial variations an LLM can infer on its own.

Add `{mdExpandTabs}` to the first code fence in a group when the tabs contain code an LLM
**cannot reliably derive** from seeing just one tab. This is rare — most times, adding only
one tab to the produced `.md` is enough.

~~~
```swift {tabTitle:Swift} {mdExpandTabs}
SentrySDK.start { options in
    options.dsn = "..."
}
```

```objc {tabTitle:Objective-C}
[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
    options.dsn = @"...";
}];
```
~~~

**Expand** — the code is too different for an LLM to infer:
- Different languages: Swift / Objective-C, cross-language guides (JS/Python/PHP/Ruby/...)
- Different setup flows: Hono guide init (Cloudflare vs Node.js `--import` vs Bun)
- Different APIs or wrappers: GCP Cloud Functions (`wrapHttpFunction` vs `wrapCloudEventFunction`), serverless async/sync handlers
- Different framework versions with distinct imports: Spring 5/6/7, Spring Boot 2/3/4, Svelte v5+ / v3
- Client / Server splits: Next.js, Remix, React Router (Replay + browser tracing vs Node integrations)
- Different platform tooling: KMP (`commonMain` / `iosApp` / `androidApp`), Flutter navigation (Navigator / GoRouter / AutoRoute)
- Install methods with different patterns: npm (`import`) vs CDN (`<script>`) vs Loader (`sentryOnLoad`)
- SDK version migration: SDK 2.x vs 1.x when APIs differ

**Collapse** (default) — an LLM can figure it out from one tab:
- Package managers: npm / yarn / pnpm, pip / uv, .NET CLI / NuGet
- Module format: ESM / CommonJS (same API, different import syntax)
- Config file formats: JSON / TOML, properties / yml
- Java / Kotlin on the same platform (same APIs, syntactic sugar differences)
- Runtime tabs where only the import path changes (e.g. `@sentry/hono/cloudflare` vs `@sentry/hono/node` in `platform-includes/` snippets)
- Build tools when only dependency declaration syntax differs: Gradle / Maven / SBT

## Review Checklist

When reviewing documentation:

- [ ] Does each section explain WHY before HOW?
- [ ] Is the same code pattern shown multiple times? (consolidate if yes)
- [ ] Would a developer know WHEN to use this approach?
- [ ] Can any section be shortened without losing meaning?
- [ ] Are best practices adding new info or just repeating?