code-documentation-patterns
Installation
SKILL.md
Code Documentation Patterns
Overview
Stale docs erode trust, misleading comments introduce bugs, and undocumented architectural decisions get re-litigated every six months. Use this guide to write documentation that stays accurate, helps future contributors, and scales with the codebase.
When to use: Adding a new public API, recording an architectural decision, onboarding a new team member, reviewing PRs for documentation completeness, or auditing a codebase for documentation health.
Quick Reference
| Pattern | Core Idea | Primary Red Flag |
|---|---|---|
| Architecture Decision Record | Document context, decision, and consequence in a lightweight file | Decision made verbally, never written down; team re-debates the same choice |
| API Documentation (OpenAPI/AsyncAPI) | Machine-readable contract that doubles as human-readable reference | Docs generated from code only, never from intent; drifts from actual behavior |
| JSDoc / Docstrings | Inline structured comments on public interfaces | Missing param types, stale return descriptions, no examples for complex behavior |
| README Standards | Orientation doc covering purpose, setup, usage, and runbook | README last updated two major versions ago; no local-run instructions |
| Inline Documentation | Explain why, not what; annotate non-obvious decisions | Comments restate the code; intent buried; nothing explains the workaround |
| Technical Debt Register | Intentional debt tracked with owner, cost, and due date | // TODO comments with no date, owner, or ticket reference |
| Documentation Anti-Patterns | Stale docs, misleading comments, commented-out code | Committed code blocks that "might be useful later" |