| name | documentation-standards |
| description | Documentation methodology. What to document, format templates, and accuracy-first principles. Injected into Lois Lane's context.
|
| user-invocable | false |
| disable-model-invocation | true |
| last_reviewed | "2026-04-28T00:00:00.000Z" |
Documentation Standards
This guides what documentation you produce and how you produce it. The core
principle is accuracy — document what the code does, not what the plan said
it would do.
What to Document
Assess what changed and document accordingly:
New API Endpoints
For each new endpoint, document:
- HTTP method and path
- Request body/parameters (with types and required/optional)
- Response format (with example)
- Authentication/authorization requirements
- Error responses
New Configuration
For new environment variables or config options:
- Name and purpose
- Default value (if any)
- Valid values/format
- Where to set it (env var, config file, etc.)
Architecture Changes
For significant structural changes:
- What changed and why
- New components and their responsibilities
- How they fit into the existing architecture
- Data flow diagrams if the flow changed
User-Facing Features
If the change affects end users:
- What the feature does (from the user's perspective)
- How to use it
- Any limitations or known issues
Format Guidelines
- Match the project's existing documentation style
- Use the project's existing doc file locations (README, docs/, wiki, etc.)
- Prefer examples over descriptions — show a curl command, not just text
- Keep it concise — one clear sentence beats three vague ones
- Use code blocks for commands, paths, and data structures
Accuracy Protocol
- Read the code, not just the plan or architecture doc
- If you find a discrepancy between plan and code, document the CODE
- Flag discrepancies as a note: "Note: The architecture doc specifies X,
but the implementation uses Y."
- Test any commands or instructions you document if possible
Placement and Structure
When a project has both README.md and a docs/ directory: API docs and guides go
in docs/. README covers setup, quickstart, and links to docs/.
CHANGELOG.md: update for user-facing changes. Follow Keep a Changelog format —
sections are Added, Changed, Deprecated, Removed, Fixed, Security. Unreleased
changes go under ## [Unreleased].
Breaking changes: document in both CHANGELOG and the relevant API or migration
docs. Call out explicitly what breaks and what the migration path is. A breaking
change documented only in one place will be missed.
What NOT to Document
- Internal implementation details that don't affect users or developers
- Temporary workarounds (these should be tickets, not docs)
- Aspirational features that aren't implemented yet
- Performance characteristics you haven't measured
