Documentation Standards Agent Rules
Project Context
You are writing and maintaining technical documentation for a software project. Documentation is a first-class deliverable — outdated or missing docs are bugs.
README Structure
- Every project must have a `README.md` in the root with: title, one-sentence description, quick start (3–5 steps), prerequisites, configuration, contributing, and license.
- Lead with the simplest useful example — show `npm install && npm run dev` before explaining architecture.
- Use badges for status: CI, coverage, version, and license — place them immediately below the title.
- Document all required environment variables in a table with name, required/optional, and description.
- Keep the README under two screens of content — link to deeper documentation in a `docs/` directory.
- Test the README quick start steps in a fresh environment quarterly — they become stale silently.
Code Documentation
- Write comments to explain **why**, not **what** — the code shows what; comments explain intent, constraints, and non-obvious decisions.
- Document public APIs and exported functions with JSDoc, TSDoc, or language-equivalent docstrings.
- Every public function needs: a one-sentence summary, `@param` annotations with type and description, `@returns` annotation, and `@throws` for expected error cases.
- Add `// TODO(username, AGE-123): description` for deferred work — include the author and issue reference.
- Use `// NOTE: ` for important context that is not obvious from the code, `// HACK: ` for known workarounds with an explanation.
- Delete stale comments immediately — a comment that contradicts the code is worse than no comment at all.
- Avoid redundant comments: `// increment counter` above `counter++` adds no value.
JSDoc / TSDoc Style
- Use `/** ... */` block comments for public APIs — inline `//` for internal explanations.
- Write `@param name - Description` with a dash after the param name (TSDoc style).
- Include `@example` blocks for non-trivial functions to show typical usage.
- Mark deprecated APIs with `@deprecated Use {@link newFunction} instead` and document the migration path.
- Use `@internal` to signal APIs that are public but not intended for external consumption.
- Generate API documentation from docstrings with `typedoc` (TypeScript) or `pdoc` (Python) in CI.
Architecture Decision Records (ADRs)
- Create an ADR for every significant technical decision: technology choices, architectural patterns, rejected alternatives.
- Store ADRs in `docs/adr/` numbered sequentially: `0001-use-postgresql.md`, `0002-adopt-event-sourcing.md`.
- Use this structure: Status (Accepted/Deprecated/Superseded), Context (the problem), Decision (what was chosen), Consequences (pros and cons).
- Mark superseded ADRs with a reference to the new ADR — never delete old records; they capture reasoning that may be revisited.
- Review ADRs during onboarding so new team members understand why the codebase is designed the way it is.
CHANGELOG
- Maintain `CHANGELOG.md` following the Keep a Changelog format with `[Unreleased]` and versioned sections.
- Categorize changes under `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`.
- Write changelog entries for humans, not commits: `Added user export to CSV` not `feat(users): add exportToCsv method`.
- Generate changelogs from conventional commits using `conventional-changelog` or `release-please` in CI.
- Publish changelog entries alongside release tags so users can quickly understand what changed.
API Reference Documentation
- Maintain an OpenAPI spec as the single source of truth for REST API documentation.
- Generate client-facing docs from the OpenAPI spec using Swagger UI, Redoc, or equivalent.
- Keep schema `examples` realistic and representative of actual response shapes.
- Document all error codes with the conditions that trigger them and suggested remediation.
- Version API documentation alongside the API — `/docs/v1/`, `/docs/v2/`.
Writing Style
- Use active voice and present tense: `The function returns a User object`, not `A User object is returned`.
- Write for your audience: assume technical literacy but not intimate knowledge of the codebase.
- Define acronyms and internal terms on first use.
- Use numbered lists for sequential steps; use bullet lists for unordered items.
- Include diagrams (Mermaid, PlantUML) for complex flows, data models, and architecture — embed them in Markdown.
- Proofread documentation for grammar and spelling before committing — use a spellcheck tool.
- Treat documentation PRs with the same rigor as code PRs — review and approve before merging.
Documentation
