majiayu000 Documentation System
A system for writing clear, maintainable documentation optimized for both humans and AI navigation.
Core Philosophy
- Document logic, not syntax - Explain how things work together, not what's obvious from code
- Progressive disclosure - Overview first, details on demand
- AI-navigable - Clear structure so AI can find and update the right docs
- Minimal but complete - Include what's needed, nothing more
Folder Structure
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.
When to Use Each Reference
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 |
Quick Reference
Creating a New Doc
- Determine type: system concept, package doc, or guide
- Check if it should extend an existing doc instead
- Use appropriate template from
references/templates/ - Add to relevant
index.mdnavigation
Finding Existing Docs
- Start at
docs/index.mdfor overview - System-level concepts →
docs/system/ - Package specifics →
docs/packages/[package-name].md - How-to instructions →
docs/guides/
Updating Docs After Code Changes
- Identify which docs reference the changed code
- Check if descriptions are still accurate
- Update code references (file paths, line numbers if used)
- Don't remove content without checking cross-references
What NOT to Document
- Implementation details that change frequently
- Information obvious from well-named code
- Auto-generatable content (API signatures, type definitions)
- Speculative future plans (use project tracking instead)