documentation

---
name: documentation
description: >
license: MIT
---

# Documentation

Write docs that developers actually read. Based on Stripe API docs, Standard Readme, Keep a Changelog, and OpenAPI.

## Sub-Commands

| Command | Description |
|---------|-------------|
| `readme` | Generate a README from project files |
| `api` | Generate API docs from OpenAPI spec or route handlers |
| `changelog` | Generate changelog from conventional commits |
| `kb` | Write a knowledge base article |

## README Structure

```
# Project Name [Badges]

> One-line description

## Features (3-6 quantified benefits)
## Quick Start — copy-paste runnable (no placeholders, no omitted imports)
## API Reference — every export in table format
## Examples — 2-3 real-world scenarios
## Configuration — env vars, config file, CLI flags
## Contributing — dev setup commands
## License — SPDX identifier
```

### The Hook (first paragraph)

Answers: what (5 words), who, why.

Bad: "A React component library for building modern user interfaces."
Good: "Buttons, modals, forms, done right. No design debt. Zero dependencies."

### Quick Start Rules

Copy-paste runnable. No omitted imports. No placeholders. No "coming soon". Include expected output.

### Badge Requirements

| Badge | Required? |
|-------|-----------|
| CI (build status) | Yes |
| Package version | Yes |
| License | Yes |
| Coverage | Recommended |

## API Documentation

### Structure per Endpoint
```
### [METHOD] [Path]
**Description**: one sentence
**Auth required**: Yes/No [type]
**Request**: Headers, Parameters (path/query/body)
**Response 200**: Body with example
**Error responses**: 400, 401, 404, 500 with descriptions
```

### Rules per Endpoint
- [ ] Request example (curl + one SDK)
- [ ] Response example with ALL fields
- [ ] Error responses for ALL possible status codes
- [ ] Pagination docs (if applicable)
- [ ] Rate limit headers documented

## Changelog Format

```
## [2.1.0] - 2026-05-16

### Added
- New feature (#PR)

### Changed
- Behavior change with migration note (#PR)

### Fixed
- Bug fix (#PR)

### Deprecated / Removed / Security
```

Rules: Keep a Changelog format. Every entry links to PR. Migration notes for breaking changes. Unreleased section at top. Semantic versioning. Explain WHY not just WHAT.

## Knowledge Base

### Article Format
```
Title: as a question user would search for
Context: 1-2 sentences — who, what product/feature
Steps: numbered, one action per step, action verb first
Expected result: after last step
Escalation: if it still doesn't work
```

Rules: One action per step. Bold UI labels exactly as they appear. Max 15 words per step. No jargon.

## Production Checklist

- [ ] All examples tested from clean environment
- [ ] No "TODO", "coming soon", "TBD", placeholder text
- [ ] Consistent tone across all sections
- [ ] Every link resolves
- [ ] License badge matches LICENSE file
- [ ] API docs: curl + SDK example per endpoint
- [ ] Changelog: unreleased section present, versions correct
- [ ] KB: tested by someone unfamiliar with the product

## Workflow

1. **Identify document type** — README, API docs, changelog, or knowledge base article. Each has a distinct structure and rule set.
2. **Gather source material** — for README: project files, package.json, build system. For API: OpenAPI spec or route handlers. For changelog: git log. For KB: product expertise.
3. **Apply the template** — README: hook → features → quick start → API → examples → config → contributing → license. API: method → path → description → auth → request → response → errors.
4. **Fill every section with real data** — no "TODO", "coming soon", "TBD", placeholder text. Quick start must be copy-paste runnable. API docs need curl + SDK examples.
5. **Verify everything** — test quick start from clean environment. Check every link resolves. Confirm license badge matches LICENSE file. KB: test steps as an unfamiliar user.
6. **Cut the generic** — remove default template comments. Strip "write unit tests" style advice. Every sentence must convey a specific convention or fact about this project.

## Error Handling

| Cause | Fix |
|-------|-----|
| Quick start commands fail from a clean environment | Test every command from scratch. Ensure no omitted imports, no assumed global state, no missing env vars. |
| API docs missing error response codes | Document all possible status codes for every endpoint: 400 (validation), 401 (auth), 403 (forbidden), 404 (not found), 500 (server error). |
| Changelog entry lacks migration notes for breaking changes | Every breaking change must include: what changed, why, and the exact migration path. Link to the PR. |
| KB article steps don't produce expected result when followed | Have someone unfamiliar with the product walk through the steps. Fix any ambiguity or missing context. |
| Links in documentation resolve to 404 or redirect | Check every link. Prefer permalinks. Verify external links haven't moved. Use web archive as fallback for critical references. |
| README badges show incorrect or outdated status | Verify CI badge matches current pipeline. Version badge matches latest release. Coverage badge matches current report. |
| API docs example response doesn't match actual API output | Generate response examples from actual API output, not from spec definitions. Update when the API changes. |
| Default README template published with unfilled sections | Remove all template comments and TODO markers before publishing. If a section has no content, omit it rather than leaving a placeholder. |

## Anti-Patterns

| Anti-Pattern | Correct |
|--------------|---------|
| Default README (template unfilled) | Remove all template comments. Fill every section. |
| "Coming soon" features | Ship or hide. Never show unfinished. |
| Untested install instructions | Test from scratch in clean environment. |
| API docs without examples | Every function needs a runnable example. |
| Changelog without migration notes | Always include migration path for breaking changes. |
| KB with no expected result | End every step with "You should see..." |
| Example code with secrets | Use placeholder env vars. Never real values. |

## API Documentation Patterns

### OpenAPI → Docs
```bash
npx @redocly/cli build-docs openapi.yaml -o docs.html
npx @scalar/api-reference openapi.yaml
```

### README Template
1. Title + one-liner, 2. Quick start (install + first command), 3. Features (bullets), 4. Architecture (diagram), 5. API (link), 6. Contributing (link), 7. License

## Changelog Automation

```bash
# Generate from conventional commits
npx standard-version
npx changelogen --from v1.0.0 --to HEAD

# Keep a Changelog format
## [version] - YYYY-MM-DD
### Added | Changed | Deprecated | Removed | Fixed | Security
```

## Sources

- Standard Readme specification
- Stripe API documentation standards
- Keep a Changelog (keepachangelog.com)
- Conventional Commits (conventionalcommits.org)
- OpenAPI Specification (openapis.org)
- Zendesk / Intercom — KB standards