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
markdown- [ ] 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
