Standards for documenting codebases. Use when writing documentation, deciding where docs should go, reviewing doc quality, or updating docs after code changes. Covers folder structure, content guidelines, and maintenance workflows.
A system for writing clear, maintainable documentation optimized for both humans and AI navigation.
Documentation lives in docs/ with three top-level folders:
docs/
├── index.md # Entry point: what is this codebase, how to navigate
├── system/ # How the system works (capabilities, concepts, flows)
├── packages/ # Per-package documentation
└── guides/ # Task-oriented how-tos
| Folder | Question It Answers |
|---|
system/ | "What does this system do? How does X work?" |
packages/ | "What does package Y do internally?" |
guides/ | "How do I accomplish Z?" |
Each folder has an index.md with navigation links and descriptions.
Read these for detailed guidance:
| Reference | When to Read |
|---|---|
| structure.md | Creating new docs, reorganizing, deciding where something goes |
| content.md | Writing or reviewing doc content, style questions |
| maintenance.md | Code changed, checking if docs need updates |
| templates/ | Starting a new doc, need a concrete starting point |
references/templates/index.md navigationdocs/index.md for overviewdocs/system/docs/packages/[package-name].mddocs/guides/