| name | documentation-writing |
| version | 1.0.0 |
| description | Writing clear, discoverable software documentation following the Eight Rules and Diataxis framework. Use when creating README files, API docs, tutorials, how-to guides, or any project documentation. Automatically enforces docs/ location, linking requirements, and runnable examples. |
| source_urls | ["https://diataxis.fr/","https://www.writethedocs.org/guide/writing/docs-principles/","https://github.blog/developer-skills/documentation-done-right-a-developers-guide/"] |
| auto_activates | ["write documentation","create docs","document this feature","create a README","write a tutorial","api docs","how-to guide"] |
| token_budget | 1800 |
Documentation Writing Skill
Purpose
Creates high-quality, discoverable documentation following the Eight Rules and Diataxis framework. Ensures all docs are properly located, linked, and contain real runnable examples.
When I Activate
I load automatically when you mention:
- "write documentation" or "create docs"
- "document this feature/module/API"
- "create a README" or "write a tutorial"
- "explain how this works"
- Any request to create markdown documentation
Core Rules (MANDATORY)
The Eight Rules
- Location: All docs in
docs/ directory
- Linking: Every doc linked from at least one other doc
- Simplicity: Plain language, remove unnecessary words
- Real Examples: Runnable code, not "foo/bar" placeholders
- Diataxis: One doc type per file (tutorial/howto/reference/explanation)
- Scanability: Descriptive headings, table of contents for long docs
- Local Links: Relative paths, context with links
- Currency: Delete outdated docs, include update metadata
What Stays OUT of Docs
Never put in docs/:
- Status reports or progress updates
- Test results or benchmarks
- Meeting notes or decisions
- Plans with dates
- Point-in-time snapshots
Where temporal info belongs:
- Test results → CI logs, GitHub Actions
- Status updates → GitHub Issues
- Progress → Pull Request descriptions
- Decisions → Commit messages
Quick Start
Creating a New Document
# [Feature Name]
Brief one-sentence description of what this is.
## Quick Start
Minimal steps to get started (3-5 steps max).
## Contents
- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)
## Configuration
Step-by-step setup with real examples.
## Usage
Common use cases with runnable code.
## Troubleshooting
Common problems and solutions.
Document Types (Diataxis)
| Type | Purpose | Location | User Question |
|---|
| Tutorial | Learning | docs/tutorials/ | "Teach me how" |
| How-To | Doing | docs/howto/ | "Help me do X" |
| Reference | Information | docs/reference/ | "What are the options?" |
| Explanation | Understanding | docs/concepts/ | "Why is it this way?" |
Workflow
Step 1: Determine Document Type
Ask: What is the reader trying to accomplish?
- Learning something new → Tutorial
- Solving a specific problem → How-To
- Looking up details → Reference
- Understanding concepts → Explanation
Step 2: Choose Location
docs/
├── tutorials/ # Learning-oriented
├── howto/ # Task-oriented
├── reference/ # Information-oriented
├── concepts/ # Understanding-oriented
└── index.md # Links to all docs
Step 3: Write with Examples
Every concept needs a runnable example:
from amplihack import analyze
result = analyze("src/main.py")
print(f"Complexity: {result.score}")
Step 4: Link from Index
Add entry to docs/index.md:
- [New Feature Guide](./howto/new-feature.md) - How to configure X
Step 5: Validate
Checklist before completion:
Navigation Guide
When to Read Supporting Files
reference.md - Read when you need:
- Complete frontmatter specification
- Detailed Diataxis type definitions
- Markdown style conventions
- Documentation review checklist
examples.md - Read when you need:
- Full document templates for each type
- Real-world documentation examples
- Before/after improvement examples
- Complex documentation patterns
Anti-Patterns to Avoid
| Anti-Pattern | Why It's Bad | Better Approach |
|---|
| "Click here" links | No context | "See auth config" |
| foo/bar examples | Not realistic | Use real project code |
| Wall of text | Hard to scan | Use headings and bullets |
| Orphan docs | Never found | Link from index |
| Status in docs | Gets stale | Use Issues/PRs |
Retcon Documentation Exception
When writing documentation BEFORE implementation (document-driven development):
# [PLANNED - Implementation Pending]
This document describes the intended behavior of Feature X.
## Planned Interface
```python
# [PLANNED] - This API will be implemented
def future_function(input: str) -> Result:
"""Process input and return result."""
pass
```
Once implemented, remove the [PLANNED] markers and update with real examples.
---
**Full reference**: See [reference.md](./reference.md) for complete specification.
**Templates**: See [examples.md](./examples.md) for copy-paste templates.
