---

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

Rules

Avoid

Patterns

Copy# 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

See Also

• Related Feature

Copy
```markdown
# Pattern 2: API endpoint documentation
## POST /api/resource/

Creates a new resource.

### Request
```json
{
  "name": "string",
  "value": 123
}

Response (201)

Copy{
  "id": 1,
  "name": "string",
  "created_at": "2026-01-13T00:00:00Z"
}

Errors

Copy
## 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 |