Documentation Structure
Standard patterns for organizing documentation files and directories.
Directory Conventions
/docs Directory
User-facing documentation lives in /docs at the project root. This directory is always included in documentation scans regardless of .gitignore patterns.
Subdirectory Organization
Create subdirectories that mirror actual code extensions:
docs/
├── api/ # REST API documentation
│ ├── authentication.md # Auth endpoints
│ └── users.md # User endpoints
├── components/ # UI component documentation
│ ├── forms.md # Form components
│ └── navigation.md # Navigation components
└── configuration/ # Configuration documentation
└── settings.md # Application settingsHierarchical Depth
Match the depth of code organization. If code has nested extensions, documentation can have nested subdirectories. Avoid unnecessary nesting.
File Naming
Descriptive Names
File names describe the functionality being documented:
authentication.mdnotauth.mduser-management.mdnotusers.mdform-validation.mdnotforms.md
No Generic Names
Never use generic names like readme.md, index.md, or overview.md in subdirectories. Each file should have a specific, descriptive name.
Directory Entry Points
When a directory needs an introductory file (architecture overview, component listing, how pieces connect), name it after the directory:
blocks/
├── blocks.md # Entry point: "What is the blocks extension?"
├── class-wp-block.md # Specific component
├── functions.md # Function reference
└── hooks.md # Hook referenceThe pattern {directory}/{directory}.md serves as the natural entry point:
- api/api.md — API extension introduction
- cache/cache.md — Cache system overview
- rest-api/rest-api.md — REST API architecture
This is descriptive (tells you it’s THE blocks doc) while serving as an obvious starting point for navigation.
Kebab-Case
Use kebab-case for all file names: user-authentication.md, api-reference.md
File Structure
H1 Title
Every documentation file starts with a single H1 title describing what the file covers:
# User Authentication
Content about user authentication...Section Headers
Use H2 for major sections, H3 for subsections:
# User Authentication
## Login Methods
### Email/Password
### OAuth Providers
## Session ManagementCode Examples
Include code examples from actual implementation. Use appropriate language hints:
```php
$user = get_user_by('email', $email);## Content Organization
### Component Files
For component documentation, organize by:
1. Overview (what the component does)
2. Properties/Methods (complete listing)
3. Usage (code examples from actual implementation)
### API Documentation
For API endpoint documentation, organize by:
1. Endpoint (method and path)
2. Authentication requirements
3. Parameters
4. Response format
5. Example request/response
### Configuration Documentation
For configuration documentation, organize by:
1. Option name
2. Type and default value
3. Description
4. Valid values
## Exclusions from /docs
These belong elsewhere, not in `/docs`:
- CLAUDE.md / AGENTS.md (project root)
- README.md (project root or component roots)
- CHANGELOG.md (project root)
- Build documentation (in code comments or separate dev docs)
## Documentation Commands
Use `homeboy docs audit <component>` to validate existing docs and find gaps. Use `homeboy docs map <component>` to generate a machine-optimized codebase map. Use `homeboy docs generate` to create files in bulk from a JSON spec.