# Documentation Rules

## What to Document
- Public API functions: parameters, return types, error conditions, examples.
- Architecture decisions: why a particular approach was chosen (ADRs).
- Setup and installation: prerequisites, steps, common issues.
- Configuration: all options, defaults, environment variables.
- Non-obvious behavior: edge cases, gotchas, workarounds.

## What Not to Document
- Obvious code (getters, setters, simple wrappers).
- Implementation details that change frequently.
- Anything the type system already expresses.
- Temporary workarounds without a tracking issue.

## Keep Docs Current
- Update documentation in the same PR that changes the code.
- Review docs in code review. Stale docs are worse than no docs.
- Use CI to verify that documentation examples compile or run.
- Keep CLAUDE.md or AGENTS.md updated with current project context.

## Documentation Formats
- Inline code comments: explain **why**, not what. One line, placed above the code.
- JSDoc/docstrings: for public APIs. Include parameters, returns, throws, and an example.
- README: installation, quick start, configuration, contribution guidelines.
- CLAUDE.md: project context, conventions, build commands, key architecture decisions.
- ADRs: date, status, context, decision, consequences. Store in `docs/adr/`.

## Style Guidelines
- Use concrete examples, not abstract descriptions.
- Write for the reader who will maintain this code in 6 months.
- Use consistent terminology. Define domain terms in a glossary if needed.
- Keep sentences short. One idea per paragraph.
- Use code blocks with language tags for syntax highlighting.
- Use tables for option lists, comparison matrices, and configuration references.

## README Structure
1. Project name and one-line description.
2. Installation / quick start (copy-paste ready).
3. Usage examples (the most common use case first).
4. Configuration reference.
5. Contributing guidelines.
6. License.