documentation-writing
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.
When & Why to Use This Skill
This Claude skill streamlines the creation of professional software documentation by strictly implementing the Diataxis framework and the 'Eight Rules' of technical writing. It ensures all documentation is discoverable, consistently formatted, and located within a standardized directory structure, while prioritizing runnable code examples over placeholders to enhance developer experience and project maintainability.
Use Cases
- Case 1: Generating comprehensive README files and project overviews for new software repositories to improve onboarding.
- Case 2: Converting complex source code into structured Diataxis-compliant documents, including Tutorials, How-To guides, and Technical References.
- Case 3: Refactoring existing messy documentation into a centralized 'docs/' directory with automated cross-linking and scanable headings.
- Case 4: Creating high-quality API documentation that features real-world, runnable code examples instead of generic 'foo/bar' placeholders.
- Case 5: Auditing and updating project documentation to remove outdated temporal information (like status reports) and ensure content currency.
| 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. |
| - https | //github.blog/developer-skills/documentation-done-right-a-developers-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:
# Example: Analyze file complexity
from amplihack import analyze
result = analyze("src/main.py")
print(f"Complexity: {result.score}")
# Output: Complexity: 12.5
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:
- File in
docs/directory - Linked from index or parent doc
- No temporal information
- All examples tested
- Follows one Diataxis type
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.