Section 14 · Observability
Documentation
Ensure all features are documented, complex systems have dedicated explanations, and documentation stays current with the codebase.
This guide walks you through auditing a project's documentation, ensuring all features are documented, complex systems have dedicated explanations, and documentation stays current with the codebase.
The Goal: Self-Explaining Systems
Code tells you what, documentation tells you why. Good documentation enables humans and AI agents to understand, debug, and extend systems without tribal knowledge or archaeology.
- Accessible — Feature documentation exists in-repo (preferred) or externally, readable by both humans and AI agents
- Complete — Complex systems (payments, fulfillment, admin, integrations) have dedicated prose beyond code comments
- Current — Documentation stays fresh; staleness signals are checked and addressed
- In-repo first — Auth-walled external docs have in-repo equivalents for AI accessibility
Before You Start
- Know the project's documentation locations (in-repo, Notion, GitBook, wiki)
- Identify complex systems in the project (payments, fulfillment, admin, integrations)
- Have git access to check file history
general
Documentation exists covering major features, accessible to both humans and AI agents. In-repo docs preferred; external (Notion, GitBook, wiki) acceptable if accessible.
“Could a new hire understand your system without asking you?”
Complex systems (e.g., payment gateways, order fulfillment, admin features, third-party integrations) have dedicated documentation explaining flows, edge cases, and integration points.
“What happens to your payment flow if your main dev quits?”
Documentation is kept up to date with the codebase. Source files referenced in docs have not changed significantly since the doc was last updated.
“When did your docs last change alongside the code?”