Documentation Style

Good docs follow progressive disclosure: pitch first, value upfront, defer details. Trust readers to follow links for depth.

Progressive Disclosure

Start with value. Defer architecture.

1. Pitch (1–2 lines): What is it? Why does it matter?
2. Quick Start: Get running in 30 seconds
3. Core Concept: What you need to know to use it
4. Key Example: One practical example (beats three paragraphs)
5. The MOAT: The non-obvious part (this is the highest-value section)
6. Reference: Link out for deep details

Example: Good Structure

# Auth Service

Manages user sessions and permissions via OAuth2 + JWTs.

## Quick Start
[3-step setup]

## How It Works
[One paragraph explaining the JWT flow]

## The MOAT: Why JWT + Redis Cache
This is non-obvious: we store a cache in Redis that maps token → user.
Benefit: revocation is instant (no JWT blacklist list). Trade-off:
Redis must be available for auth checks (adds operational burden).

## Full Reference
[Link to official docs]

What to Lead With

Leading position is premium real estate.

Lead with value — what the reader gets from this thing — not setup steps. "Manages user sessions via OAuth2" beats "First, install Node." Setup is necessary but not valuable; it matters only after readers are convinced they want to use this.

The MOAT

The MOAT — "Moat" — is the part that isn't obvious from reading the code: the reasoning, trade-offs, and non-obvious design decisions. This is where docs earn their keep. Why was this tool chosen over alternatives? What queries does the schema optimize for? Why this rate limit? This is the material the code alone cannot convey.

Don't document what the code already says: "This function takes a userId parameter", "This class has a connect() method", "This returns a Promise". The code says all of this. Document the why, not the what.

Length Guidelines

Keep docs terse: <30 lines for simple topics, <50 for standard, <110 for complex, <180 for reference. If you exceed the ceiling by 50%, split into multiple pages or link out.

How to Write About Tradeoffs

Docs should explain the architectural decisions behind code.

Pattern:

Why [choice]?

We chose [X] over [Y and Z] because:
- [Benefit 1]
- [Benefit 2]

Trade-off: [Cost of this choice]

Example:

Why stateless auth?

We chose JWT over session storage because:
- Scales horizontally (no session replication needed)
- No database lookup on every request

Trade-off: Revocation requires extra infrastructure
(we use Redis cache for instant revocation)

Anti-Patterns

Long walkthroughs: Don't compete with official docs. Link instead and focus on the MOAT.

Multiple similar examples: Pick one good example. Five variations teach less than one example plus a clear rule.

"Best practices" lists: Trust readers. Link to opinionated guides.

Feature tables: Link to the canonical reference; focus on what matters to your use case.

Scrollable READMEs: Link liberally. Inline only the critical path.

Voice

• Active, direct: "Run this to deploy" — not "This can be run to deploy"
• No filler: Cut "in order to", "it should be noted", "as you can see"
• No marketing: "Powerful", "robust", "seamless" — drop these words
• Show, don't explain: One example beats three paragraphs of description

Related

• Plugins Overview — Where contributed plugin docs live
• Using Subagents — Briefing agents to write docs