mcouthon/agents/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.

Audience Matrix

Layer Rules

Code Comments

• Explain why, never what — the code already says what
• Mark non-obvious decisions, trade-offs, and workarounds
• Cite the durable artifact — issue/ticket, ADR, commit — for context: // Workaround for #1234. Never cite orchestration scratch (task folders, phase plans, session state)
• Delete rather than comment out dead code (use version control)
• Keep comments adjacent to the code they describe

Docstrings

• Non-obvious contracts: State the contract — params, returns, raises/throws, brief description
• Self-documenting signatures: No docstring — the name and types already carry it
• Skip entirely: Simple getters/setters, constructors with no logic, obvious wrappers
• Describe the contract (what), not the implementation (how)
• Include a usage example only when usage is genuinely non-obvious

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:

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

-[ ] Non-obvious contracts documented; self-evident signatures left bare
-[ ] Comments exceptional: why-only, no narration or restatement
-[ ] 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

Docstring Standards

Follow the standard specified by each language's instruction file. Do not invent custom formats.

When a language-specific instruction file doesn't cover documentation, apply the global rule — docstrings only where the contract is non-obvious. When one is warranted:

• 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:

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