documentation.md

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.