curiositech/devtool-documentation

Developer Tool Documentation

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

<Prerequisites callout>
- 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
\`\`\`

<Expected output>
✓ 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

1. Time-to-hello-world under 5 minutes. If it takes longer, your install is too complex.
2. Show expected output after every step. The reader needs confirmation they're on track.
3. Zero decisions. Don't ask them to choose between approaches. Pick for them. How-to guides are where options live.
4. Use realistic but simple data. "hello" is fine. "sk_test_abc123" is better than "YOUR_API_KEY".
5. 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:

1. Two-column layout: Description left, code right. Eyes never leave context.
2. Language switcher: Same endpoint in curl, Node, Python, Ruby, Go, Java, .NET.
3. Real data in examples: "cus_NffrFeUfNV2Hib" not "CUSTOMER_ID".
4. Expandable objects: Show the shape without overwhelming.
5. 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: "[email protected]",
  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) |

Docs-as-Code Workflow

The Pipeline

Author (MDX/MD) → Git Commit → PR Review → CI Checks → Deploy

CI Checks to Implement

# .github/workflows/docs-ci.yml
name: Docs CI
on: [pull_request]
jobs:
  docs-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint prose
        run: npx vale docs/         # Prose linting (style guide)
      - name: Check links
        run: npx linkinator docs/   # Dead link detection
      - name: Validate code blocks
        run: npx ts-check-md docs/  # TypeScript code blocks compile
      - name: Spell check
        run: npx cspell docs/**/*.md
      - name: Build docs
        run: npm run docs:build     # Catch build errors

Essential Docs Tooling

| Tool | Purpose | Command | |------|---------|---------| | Vale | Prose linting (Microsoft, Google style) | vale docs/ | | linkinator | Dead link detection | linkinator docs/ --recurse | | cspell | Spell checking with tech dictionaries | cspell "docs/**/*.md" | | ts-check-md | Validate TypeScript code blocks compile | ts-check-md docs/ | | remark-lint | Markdown formatting consistency | remark docs/ --use preset-lint-recommended | | Algolia DocSearch | Docs search (free for OSS) | Apply at docsearch.algolia.com |

Information Architecture

Standard Developer Docs Sitemap

docs/
├── index.md                    # Landing → quickstart CTA
├── getting-started/
│   ├── quickstart.md           # 5-min tutorial (THE most important page)
│   ├── installation.md         # All platforms, all package managers
│   └── key-concepts.md         # Mental model before diving in
├── tutorials/
│   ├── build-a-chat-app.md     # End-to-end, 15-30 min each
│   ├── real-time-dashboard.md
│   └── deploy-to-production.md
├── guides/                     # How-to guides (goal-oriented)
│   ├── authentication.md
│   ├── error-handling.md
│   ├── testing.md
│   ├── migration-from-v1.md
│   └── performance-tuning.md
├── reference/                  # API reference (exhaustive)
│   ├── client.md
│   ├── config.md
│   ├── cli.md
│   └── errors.md
├── explanation/                # Conceptual docs
│   ├── architecture.md
│   ├── how-auth-works.md
│   └── data-model.md
└── resources/
    ├── troubleshooting.md      # Common errors + solutions
    ├── faq.md
    ├── changelog.md
    └── community.md

Navigation Rules

1. Getting Started is always first in the sidebar.
2. Tutorials are numbered and sequential.
3. Guides are alphabetical and independent.
4. Reference mirrors your API surface 1:1.
5. 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

1. Docs Site — Complete documentation site (Docusaurus, Mintlify, Nextra, or Starlight)
2. Information Architecture — Sitemap and navigation structure
3. Style Guide — Voice, tone, terminology glossary (Vale config)
4. CI Pipeline — Automated docs testing (links, code, prose)
5. Templates — Page templates for each Diataxis quadrant
6. llms.txt — AI-ready documentation manifest