# 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 settings
```
### Hierarchical 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.md` not `auth.md`
- `user-management.md` not `users.md`
- `form-validation.md` not `forms.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 reference
```
The 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:
```markdown
# User Authentication
Content about user authentication...
```
### Section Headers
Use H2 for major sections, H3 for subsections:
```markdown
# User Authentication
## Login Methods
### Email/Password
### OAuth Providers
## Session Management
```
### Code Examples
Include code examples from actual implementation. Use appropriate language hints:
```markdown
```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.