technical-docs

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:

Good:

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:

Good best practice:

Sentry Docs Specific Patterns

SplitLayout Usage

Use <SplitLayout> for side-by-side text/code when:

• The code directly illustrates the text
• Both are needed to understand the concept

Don't use when:

• Showing a directory structure (use plain code block)
• The text is just "here's an example" (just show the code)

PlatformLink Usage

Link to related docs rather than repeating content:

Code Block Meta Flags

Always include filename when showing file-specific code:

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?