# Documentation > 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. - Skill: `mcouthon/documentation` (Agent Skill) - Install (CLI): `npx skillmds@latest add mcouthon/documentation` - Raw SKILL.md: https://api.skillmd.com/api/skills/mcouthon/documentation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: mcouthon (https://skillmd.com/u/mcouthon) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/mcouthon/documentation --- # 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