documentation-standards

name	documentation-standards
description	Covers ADRs, API documentation, changelogs, documentation review, and Mermaid diagrams. Use when writing ADRs, documenting APIs, maintaining changelogs, reviewing documentation quality, or creating architecture diagrams. Not for inline code comments (use code style guides) or project READMEs (use project-specific conventions).

Documentation Standards

Standards for ADRs, API docs, changelogs, and diagrams.

Contents

• Critical Rules
• Verification
• Topics

Critical Rules

• API docs reflect only what is implemented and released -- never document future or planned endpoints in API specifications; update docs AFTER features ship
• Never modify version numbers in CHANGELOG.md without explicit user approval -- new version headers require user confirmation
• CHANGELOG.md follows Loaf's Common Changelog profile -- release notes are written for humans, communicate user/operator impact, and are curated from git history rather than copied from it
• CHANGELOG entries must be release-facing -- imperative, one-line, self-describing entries with useful public references; no internal spec/task IDs, file lists, or implementation detail without user benefit

Verification

After Editing Documentation Files

CHANGELOG Validation:

• When editing CHANGELOG.md, verify entries follow the format:
  • Human impact: What changes for users, operators, or integrators?
  • Imperative: Starts with a present-tense verb such as Add, Fix, Remove, or Document
  • Self-describing: Understandable without relying on the category heading