Documentation Standards
Write documentation that serves humans and AI agents. Keep it accurate, layered, and close to the code.
"Documentation is a love letter that you write to your future self." — Damian Conway
Documentation Hierarchy
Documentation lives in layers. Each layer has a distinct audience, scope, and update cadence.
| Layer |
Audience |
Scope |
Update Frequency |
| Code comments |
Maintainers, AI agents |
Single block / decision |
Every code change |
| Docstrings |
Consumers, AI agents |
Function / class contract |
Every signature change |
| Module docs |
Team members, onboarding |
File / package purpose |
When module role changes |
| Project docs (README, guides) |
All stakeholders |
System / feature |
Every user-facing change |
| Architecture docs (ADRs) |
Maintainers, future devs |
Design decisions |
When decisions are made |
Audience Matrix
| Audience |
What They Need |
Key Layers |
| Internal maintainers |
Intent, trade-offs, edge cases |
Comments, docstrings, ADRs |
| New team members |
Orientation, key concepts, how things connect |
Module docs, README, architecture |
| External users / consumers |
How to use it, API contracts |
README, API reference, how-to guides |
| AI agents |
Purpose, contracts, intent behind decisions |
Docstrings, architecture docs, comments |
Layer Rules
Code Comments
- Explain why, never what — the code already says what
- Mark non-obvious decisions, trade-offs, and workarounds
- Reference issue/ticket numbers for context:
// Workaround for #1234
- Delete rather than comment out dead code (use version control)
- Keep comments adjacent to the code they describe
Docstrings
- Public APIs: Complete — params, returns, raises/throws, brief description
- Internal/private: Concise — one-line purpose; skip if trivially obvious
- Skip entirely: Simple getters/setters, constructors with no logic, obvious wrappers
- Describe the contract (what), not the implementation (how)
- Include a usage example for non-trivial public APIs
Module / Package Docs
- Top-of-file docstring or comment: one paragraph explaining purpose
- List key classes/functions and their roles
- Describe usage patterns and entry points
- Update when the module's responsibility changes
Project Docs
Follow the Diátaxis framework (see below). Keep docs in the repo, close to what they describe.
- README: Project purpose, quickstart, key links — the front door
- CHANGELOG: User-facing changes per release
- Architecture docs: Design decisions, system structure, component relationships
- API reference: Generated or maintained per public surface
Diátaxis Quick Reference
Four types of documentation, each serving a different user need:
| Type |
Orientation |
Answers |
Structure |
| Tutorial |
Learning |
"Follow these steps to learn X" |
Step-by-step, hands-on, minimal explanation |
| How-to Guide |
Task |
"How to accomplish X" |
Goal-oriented steps, assumes knowledge |
| Reference |
Information |
"Specification of X" |
Precise, complete, consistent structure |
| Explanation |
Understanding |
"Why X works this way" |
Conceptual, discursive, gives context |
Common mistakes:
- Mixing tutorial steps with reference details
- Writing a how-to guide as a tutorial (too many basics)
- Putting explanations in reference docs (keep them factual)
- Missing how-to guides (users know what they want to do, not where to look)
Quality Checklist
- [ ] Public APIs have complete docstrings (params, returns, raises)
- [ ] Code comments explain "why", not "what"
- [ ] No stale documentation (matches current behavior)
- [ ] User-facing changes reflected in README or relevant guides
- [ ] New modules have a brief purpose description at top of file
- [ ] Architecture-significant decisions documented (ADR or equivalent)
- [ ] Examples are runnable and up-to-date
- [ ] CHANGELOG updated for user-visible changes
Anti-Patterns
| Anti-Pattern |
Problem |
Correction |
| Comment restates the code |
Noise, drifts out of sync |
Delete or explain the why |
| Docstring describes implementation |
Couples docs to internals |
Focus on the contract (what, not how) |
| README lists features that don't exist |
Misleading, erodes trust |
Audit docs against actual behavior |
| Docs live only in PR/commit messages |
Invisible to future readers |
Move to permanent location in repo |
| Over-documenting trivial code |
Clutter, maintenance burden |
Skip obvious getters/setters/constructors |
| Copy-pasting docstrings across overloads |
Drift between copies |
Document the base, reference it from overloads |
| Huge top-of-file comment blocks |
Nobody reads them |
Keep to one paragraph; link to detailed docs |
Docstring Standards
Follow the standard specified by each language's instruction file. Do not invent custom formats.
| Language |
Standard |
Reference |
| Python |
Google style |
python.instructions.md — Documentation section |
| TypeScript |
TSDoc |
TSDoc conventions |
| JavaScript |
JSDoc |
JSDoc conventions |
When a language-specific instruction file doesn't cover documentation, apply these defaults:
- Public functions: brief description +
@param + @returns + @throws
- Classes: brief description + constructor params
- Interfaces/types: brief description of purpose and usage context
Agent-Specific Guidance
AI agents consume documentation differently than humans. Optimize for both.
What helps agents most:
| Documentation Element |
Agent Benefit |
| Docstrings with typed params |
Navigation, correct usage, type inference |
| Module-level purpose comments |
Understanding component responsibility |
| Architecture docs |
High-level context for cross-cutting changes |
| "Why" comments |
Making correct decisions about modifications |
| Explicit contracts (pre/post conditions) |
Safe refactoring boundaries |
Principles:
- Keep docs close to code — agents search files, not wikis
- Structured formats (tables, lists) are easier to parse than prose
- Be explicit about edge cases and invariants in docstrings
- Name things well — good names reduce the documentation needed
- When docs and code disagree, the code is right — fix the docs
1---2name: documentation3description: Documentation standards and best practices for code changes. Use when writing or reviewing documentation, adding public APIs, making user-facing changes, or checking documentation quality. Triggers on: 'use documentation mode', 'document', 'documentation', 'docstring', 'add docs', 'update docs', 'documentation review', 'API documentation', 'README update'. Full access mode - can write documentation and update code comments.4---56# Documentation Standards78Write documentation that serves humans and AI agents. Keep it accurate, layered, and close to the code.910> "Documentation is a love letter that you write to your future self." — Damian Conway1112## Documentation Hierarchy1314Documentation lives in layers. Each layer has a distinct audience, scope, and update cadence.1516| Layer | Audience | Scope | Update Frequency |17| ----------------------------- | ------------------------ | ------------------------- | ------------------------ |18| Code comments | Maintainers, AI agents | Single block / decision | Every code change |19| Docstrings | Consumers, AI agents | Function / class contract | Every signature change |20| Module docs | Team members, onboarding | File / package purpose | When module role changes |21| Project docs (README, guides) | All stakeholders | System / feature | Every user-facing change |22| Architecture docs (ADRs) | Maintainers, future devs | Design decisions | When decisions are made |2324## Audience Matrix2526| Audience | What They Need | Key Layers |27| -------------------------- | --------------------------------------------- | --------------------------------------- |28| Internal maintainers | Intent, trade-offs, edge cases | Comments, docstrings, ADRs |29| New team members | Orientation, key concepts, how things connect | Module docs, README, architecture |30| External users / consumers | How to use it, API contracts | README, API reference, how-to guides |31| AI agents | Purpose, contracts, intent behind decisions | Docstrings, architecture docs, comments |3233## Layer Rules3435### Code Comments3637- Explain **why**, never **what** — the code already says what38- Mark non-obvious decisions, trade-offs, and workarounds39- Reference issue/ticket numbers for context: `// Workaround for #1234`40- Delete rather than comment out dead code (use version control)41- Keep comments adjacent to the code they describe4243### Docstrings4445- **Public APIs**: Complete — params, returns, raises/throws, brief description46- **Internal/private**: Concise — one-line purpose; skip if trivially obvious47- **Skip entirely**: Simple getters/setters, constructors with no logic, obvious wrappers48- Describe the **contract** (what), not the **implementation** (how)49- Include a usage example for non-trivial public APIs5051### Module / Package Docs5253- Top-of-file docstring or comment: one paragraph explaining purpose54- List key classes/functions and their roles55- Describe usage patterns and entry points56- Update when the module's responsibility changes5758### Project Docs5960Follow the **Diátaxis framework** (see below). Keep docs in the repo, close to what they describe.6162- **README**: Project purpose, quickstart, key links — the front door63- **CHANGELOG**: User-facing changes per release64- **Architecture docs**: Design decisions, system structure, component relationships65- **API reference**: Generated or maintained per public surface6667## Diátaxis Quick Reference6869Four types of documentation, each serving a different user need:7071| Type | Orientation | Answers | Structure |72| ---------------- | ------------- | ------------------------------- | ------------------------------------------- |73| **Tutorial** | Learning | "Follow these steps to learn X" | Step-by-step, hands-on, minimal explanation |74| **How-to Guide** | Task | "How to accomplish X" | Goal-oriented steps, assumes knowledge |75| **Reference** | Information | "Specification of X" | Precise, complete, consistent structure |76| **Explanation** | Understanding | "Why X works this way" | Conceptual, discursive, gives context |7778**Common mistakes:**7980- Mixing tutorial steps with reference details81- Writing a how-to guide as a tutorial (too many basics)82- Putting explanations in reference docs (keep them factual)83- Missing how-to guides (users know what they want to do, not where to look)8485## Quality Checklist8687```markdown88- [ ] Public APIs have complete docstrings (params, returns, raises)89- [ ] Code comments explain "why", not "what"90- [ ] No stale documentation (matches current behavior)91- [ ] User-facing changes reflected in README or relevant guides92- [ ] New modules have a brief purpose description at top of file93- [ ] Architecture-significant decisions documented (ADR or equivalent)94- [ ] Examples are runnable and up-to-date95- [ ] CHANGELOG updated for user-visible changes96```9798## Anti-Patterns99100| Anti-Pattern | Problem | Correction |101| ---------------------------------------- | --------------------------- | ---------------------------------------------- |102| Comment restates the code | Noise, drifts out of sync | Delete or explain the **why** |103| Docstring describes implementation | Couples docs to internals | Focus on the contract (what, not how) |104| README lists features that don't exist | Misleading, erodes trust | Audit docs against actual behavior |105| Docs live only in PR/commit messages | Invisible to future readers | Move to permanent location in repo |106| Over-documenting trivial code | Clutter, maintenance burden | Skip obvious getters/setters/constructors |107| Copy-pasting docstrings across overloads | Drift between copies | Document the base, reference it from overloads |108| Huge top-of-file comment blocks | Nobody reads them | Keep to one paragraph; link to detailed docs |109110## Docstring Standards111112Follow the standard specified by each language's instruction file. Do **not** invent custom formats.113114| Language | Standard | Reference |115| ---------- | ------------ | ------------------------------------------------ |116| Python | Google style | `python.instructions.md` — Documentation section |117| TypeScript | TSDoc | TSDoc conventions |118| JavaScript | JSDoc | JSDoc conventions |119120When a language-specific instruction file doesn't cover documentation, apply these defaults:121122- Public functions: brief description + `@param` + `@returns` + `@throws`123- Classes: brief description + constructor params124- Interfaces/types: brief description of purpose and usage context125126## Agent-Specific Guidance127128AI agents consume documentation differently than humans. Optimize for both.129130**What helps agents most:**131132| Documentation Element | Agent Benefit |133| ---------------------------------------- | -------------------------------------------- |134| Docstrings with typed params | Navigation, correct usage, type inference |135| Module-level purpose comments | Understanding component responsibility |136| Architecture docs | High-level context for cross-cutting changes |137| "Why" comments | Making correct decisions about modifications |138| Explicit contracts (pre/post conditions) | Safe refactoring boundaries |139140**Principles:**141142- Keep docs close to code — agents search files, not wikis143- Structured formats (tables, lists) are easier to parse than prose144- Be explicit about edge cases and invariants in docstrings145- Name things well — good names reduce the documentation needed146- When docs and code disagree, the code is right — fix the docs
mcouthon