name: documentation
description: Load when editing .md files, docs/ directory, README, or CHANGELOG. Provides documentation structure and best practices for technical writing.
Documentation
Merged Skills
- technical-writing: Clear, concise documentation
- api-docs: Endpoint documentation, schemas
- guides: How-to tutorials, step-by-step instructions
⚠️ Critical Gotchas
| Category |
Pattern |
Solution |
| Stale docs |
Docs updated separately from code |
Update docs in SAME commit as code changes |
| Broken links |
Links break after file moves |
Check relative paths, use grep -r "old_path" |
| Stale examples |
Code samples don't work |
Verify examples actually run |
| Duplicate content |
Same info in multiple places |
Link to source, don't duplicate |
| Missing context |
Doc assumes knowledge |
Include prerequisites, link to background |
| No navigation |
Users can't find docs |
Update docs/INDEX.md with new entries |
Rules
| Rule |
Pattern |
| Same commit |
Doc changes in same commit as code |
| Include examples |
Code samples for every concept |
| Link don't duplicate |
Reference existing docs |
| Update INDEX |
Add new docs to docs/INDEX.md |
| Verify examples |
Test that code samples work |
Avoid
| ❌ Bad |
✅ Good |
| Docs in separate PR |
Same commit as code |
| Duplicate content |
Link to existing docs |
| No code examples |
Include runnable samples |
| Orphan docs |
Update INDEX.md |
| Assumed knowledge |
State prerequisites |
Patterns
# Pattern 1: Feature documentation
# Feature Name
## Overview
Brief description of what this feature does and why it exists.
## Prerequisites
- Requirement 1
- Requirement 2
## Usage
```python
# Example code that actually works
from module import feature
result = feature.do_something()
Configuration
| Option |
Type |
Default |
Description |
option1 |
string |
"default" |
What it does |
See Also
```markdown
# Pattern 2: API endpoint documentation
## POST /api/resource/
Creates a new resource.
### Request
```json
{
"name": "string",
"value": 123
}
Response (201)
{
"id": 1,
"name": "string",
"created_at": "2026-01-13T00:00:00Z"
}
Errors
| Code |
Description |
| 400 |
Invalid request body |
| 401 |
Unauthorized |
## Templates (Diátaxis Framework)
| Template | Type | Use For | Location |
|----------|------|---------|----------|
| `.github/templates/doc_tutorial.md` | Tutorial | Learning-oriented guides | `docs/guides/` |
| `.github/templates/doc_guide.md` | How-To | Task-oriented instructions | `docs/guides/` |
| `.github/templates/doc_reference.md` | Reference | API specs, config lookup | `docs/technical/` |
| `.github/templates/doc_explanation.md` | Explanation | Architecture, concepts | `docs/architecture/` |
| `.github/templates/doc_analysis.md` | Analysis | Reports, audits, metrics | `docs/analysis/` |
## Structure
| Content Type | Location | Purpose |
|--------------|----------|---------|
| How-to guides | `docs/guides/` | Task-oriented tutorials |
| Feature docs | `docs/features/` | Feature explanations |
| API reference | `docs/technical/` | API specs, schemas |
| Architecture | `docs/architecture/` | Design decisions |
| Analysis/Reports | `docs/analysis/` | Audits, metrics, reports |
| Quick start | `README.md` | Getting started |
| Navigation | `docs/INDEX.md` | Doc discovery |
| Standards | `docs/contributing/` | Style guide, conventions |
## Commands
| Task | Command |
|------|---------|
| Find broken links | `grep -r "](.*\.md)" docs/ \| xargs -I{} test -f {}` |
| Check for stale refs | `grep -r "old_feature" docs/` |
| Update index | Edit `docs/INDEX.md` |
| Preview locally | Open .md file in VS Code preview |
By