Expert in developer tool documentation as a product. Activate on: docs site, getting started guide, API reference, developer documentation, Docusaurus, Mintlify, Nextra, ReadMe, migration guide, troubleshooting page, docs information architecture, documentation testing, llms.txt. NOT for: marketing copy (use seo-content-blogging), API design itself (use api-architect), general technical writing (use technical-writer).
Expert in developer tool documentation as a product. Activate on: docs site, getting started guide, API reference, developer documentation, Docusaurus, Mintlify, Nextra, ReadMe, migration guide, troubleshooting page, docs information architecture, documentation testing, llms.txt. NOT for: marketing copy (use seo-content-blogging), API design itself (use api-architect), general technical writing (use technical-writer).
Expert in the specific art of documenting developer tools — the "documentation as product" philosophy where docs are the UI of your API.
Activation Triggers
Activate on: "docs site", "getting started guide", "API reference", "developer documentation", "Docusaurus", "Mintlify", "Nextra", "ReadMe", "migration guide", "troubleshooting page", "docs information architecture", "documentation testing", "llms.txt", "docs-as-code", "quickstart"
NOT for: Marketing copy -> seo-content-blogging | API design itself -> api-architect | General technical writing -> technical-writer
The Diataxis Framework
Every developer docs site organizes content into four quadrants. Mixing them is the #1 cause of bad docs.
PRACTICAL THEORETICAL
┌─────────────────┬─────────────────┐
LEARNING │ TUTORIALS │ EXPLANATION │
(acquiring) │ "Learning" │ "Understanding" │
│ by doing │ why it works │
├─────────────────┼─────────────────┤
WORKING │ HOW-TO GUIDES │ REFERENCE │
(applying) │ "Achieving" │ "Information" │
│ a goal │ lookup │
└─────────────────┴─────────────────┘
Type
Reader State
Structure
Example
Tutorial
"I'm learning"
Step-by-step, controlled, no choices
"Build your first app in 5 minutes"
How-To
"I need to do X"
Goal-oriented, assumes knowledge
"How to deploy to Kubernetes"
Reference
"I need the specifics"
Exhaustive, structured, no narrative
API method signatures, config options
Explanation
"I want to understand"
Discursive, contextual, conceptual
"How authentication works under the hood"
Critical Rule: Never Mix Quadrants
A tutorial that stops to explain theory loses the learner. A reference page with narrative loses the person who just needs the method signature. Keep them separate; link between them.
Documentation Platform Decision Matrix
Platform
Best For
Cost
Setup
AI Features
Docusaurus
Open-source projects, full control
Free (MIT)
Medium (React)
Plugin ecosystem
Mintlify
Startups wanting Stripe-quality docs fast
$150-$500/mo
Low (MDX, Git)
AI search, llms.txt
Nextra
Next.js projects, content-heavy docs
Free (MIT)
Low (Next.js)
Via plugins
ReadMe
API-first companies, interactive docs
$99-$399/mo
Low (dashboard)
AI chat, auto-gen
GitBook
Team wikis, knowledge bases
Free-$199/mo
Very low
AI search
Starlight (Astro)
Performance-critical, static sites
Free (MIT)
Medium (Astro)
Plugin ecosystem
When to Choose Each
You have React devs and want total control -> Docusaurus
You want beautiful docs in a day -> Mintlify
Your whole stack is Next.js -> Nextra
Your primary artifact is an API -> ReadMe
Performance and build speed matter most -> Starlight
The Getting Started Guide: Most Important Page
The getting started page has the highest bounce rate and the highest conversion potential. It must be flawless.
Anatomy of a Great Quickstart
# Getting Started<Prerequisitescallout>- Node.js 18+
- A Supabase account (free tier works)
</Prerequisites>## 1. Install
\`\`\`bash
npm install @your-tool/cli
\`\`\`
## 2. Initialize
\`\`\`bash
npx your-tool init
\`\`\`
<Expectedoutput>
✓ Created config file at ./your-tool.config.ts
✓ Connected to your-tool cloud
</Expected output>## 3. Your First [Thing]
\`\`\`typescript
import { YourTool } from '@your-tool/sdk'
const client = new YourTool({ apiKey: process.env.YOUR_TOOL_KEY })
const result = await client.doTheThing({ input: "hello" })
console.log(result)
// => { output: "Hello, world!", latency: 42 }
\`\`\`
## What Just Happened?
[2-3 sentences explaining the mental model. Link to Explanation page.]
## Next Steps-**[Build a real app](/tutorials/build-a-chat-app)** — 15 min tutorial
-**[API Reference](/reference/client)** — All available methods
-**[How auth works](/explanation/authentication)** — Under the hood
Quickstart Rules
Time-to-hello-world under 5 minutes. If it takes longer, your install is too complex.
Show expected output after every step. The reader needs confirmation they're on track.
Zero decisions. Don't ask them to choose between approaches. Pick for them. How-to guides are where options live.
Use realistic but simple data."hello" is fine. "sk_test_abc123" is better than "YOUR_API_KEY".
End with a working thing. Not "you're ready to explore!" but a visible, running result.
API Reference Best Practices
What Stripe Gets Right
Stripe's API reference is the gold standard because of:
Two-column layout: Description left, code right. Eyes never leave context.
Language switcher: Same endpoint in curl, Node, Python, Ruby, Go, Java, .NET.
Real data in examples: "cus_NffrFeUfNV2Hib" not "CUSTOMER_ID".
Expandable objects: Show the shape without overwhelming.
Try it: Authenticated API explorer with test keys.
API Reference Page Template
# create(params)
Creates a new [resource].
## Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | Display name (1-100 chars) |
| `email` | `string` | Yes | Must be valid email format |
| `metadata` | `Record<string, string>` | No | Up to 50 key-value pairs |
## Returns
A `Resource` object on success. Throws `ValidationError` if params invalid.
## Example
\`\`\`typescript
const user = await client.users.create({
name: "Ada Lovelace",
email: "ada@example.com",
metadata: { role: "engineer" }
})
// => { id: "usr_abc123", name: "Ada Lovelace", ... }
\`\`\`
## Errors
| Code | Meaning |
|------|---------|
| `validation_error` | Invalid parameters (see `details` array) |
| `conflict` | Email already exists |
| `rate_limited` | Too many requests (retry after `Retry-After` header) |
Troubleshooting is always findable from search and sidebar.
Migration Guide Template
Migration guides are the most underinvested doc type. They determine whether users upgrade or leave.
# Migrating from v2 to v3**Estimated time**: 15-30 minutes for most projects
**Breaking changes**: 3 (listed below)
## Before You Start- [ ] You're on v2.8+ (run `your-tool --version`)
- [ ] Your tests pass on v2
- [] You've read the [v3 announcement blog post](/blog/v3)
## Step 1: Update Dependencies
\`\`\`bash
npm install @your-tool/sdk@3
\`\`\`
## Step 2: Breaking Change — `createClient()` signature**Before (v2):**
\`\`\`typescript
const client = createClient("your-api-key")
\`\`\`
**After (v3):**
\`\`\`typescript
const client = createClient({ apiKey: "your-api-key" })
\`\`\`
**Why**: Object params are extensible. We need to add `region` and `timeout`.
**Codemod**: `npx @your-tool/codemod v2-to-v3`## Step 3: [Next Breaking Change]
[Same pattern: before/after/why/codemod]
## Deprecations (Non-Breaking)
| Deprecated | Replacement | Removal |
|-----------|-------------|---------|
| `client.query()` | `client.sql()` | v4 |
| `Config.debug` | `Config.logLevel` | v4 |
## Verification
Run your test suite. If you see these specific errors, here's what they mean:
-`TypeError: createClient is not a function` → You imported from the wrong path
-`AuthError: invalid key format` → Wrap your key in the object param
## Need Help?- [Discord #migration channel](https://discord.gg/...)
- [GitHub Discussion](https://github.com/...)
Troubleshooting Page Best Practices
Structure every troubleshooting entry as: exact error message (H2, so search engines and users find it) -> When (context) -> Why (builds trust) -> Fix (copy-pasteable commands, not "adjust your configuration"). Users paste error messages into search. Make your H2 headings match what they paste.
AI-Ready Documentation: llms.txt
Modern docs need to serve both humans and LLMs. Mintlify, Vercel, and Supabase lead here.
llms.txt Format
# Your Tool Name
> One-line description of what it does.
## Docs
- [Getting Started](https://docs.your-tool.com/quickstart): Install and run your first query
- [Authentication](https://docs.your-tool.com/auth): API keys, OAuth, service accounts
- [API Reference](https://docs.your-tool.com/reference): All endpoints and methods
## Optional
- [GitHub](https://github.com/your-tool)
- [Status](https://status.your-tool.com)
Best Practices for LLM Discoverability
Segment by language/framework like Supabase does (JS, Python, Dart, etc.)
Include full code examples — LLMs learn from complete, working snippets
Use consistent headings — LLMs use H2/H3 structure for context windows
Provide llms-full.txt — complete content dump for RAG systems
Anti-Patterns
1. The Wall of Text Quickstart
Symptom: Getting started page is 2000 words before the first code block.
Fix: First code block within 30 seconds of scrolling. Move context to Explanation pages.
2. Outdated Code Examples
Symptom: Examples use deprecated APIs, wrong import paths, old syntax.
Fix: Test code examples in CI. Use ts-check-md or pytest-codeblocks.
3. Missing Error Documentation
Symptom: Users get Error: E4012 with no explanation anywhere in docs.
Fix: Every error code gets a troubleshooting entry. Link from error messages to docs.
4. The "See Also" Graveyard
Symptom: Pages end with 15 "See also" links, none obviously relevant.
Fix: Max 3 next steps, each with a clear reason why the reader would go there.
5. Reference Docs Without Examples
Symptom: Method signature documented, but no usage example.
Fix: Every method gets at least one example with realistic data and expected output.
6. Tutorial That Isn't a Tutorial
Symptom: Page titled "Tutorial" but is really a concept explanation or a how-to guide.
Fix: Tutorials are step-by-step, start-to-finish, and the reader makes no decisions.
Quality Checklist
[ ] Diataxis quadrants are separated — tutorials, how-tos, reference, explanation
[ ] Getting started guide tested by a newcomer (not the author)
[ ] Time-to-hello-world measured and under 5 minutes
[ ] Every API method has at least one working example
[ ] Code examples tested in CI pipeline
[ ] Prose linted with Vale or equivalent
[ ] Dead links checked automatically
[ ] Search implemented and failed searches tracked
[ ] llms.txt deployed for AI discoverability
[ ] Migration guide exists for every breaking version
[ ] Troubleshooting covers top 10 error messages
[ ] Feedback mechanism on every page
[ ] Mobile and dark mode tested
Output Artifacts
Docs Site — Complete documentation site (Docusaurus, Mintlify, Nextra, or Starlight)
Information Architecture — Sitemap and navigation structure
