documentation-writing

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

1. Location: All docs in docs/ directory
2. Linking: Every doc linked from at least one other doc
3. Simplicity: Plain language, remove unnecessary words
4. Real Examples: Runnable code, not "foo/bar" placeholders
5. Diataxis: One doc type per file (tutorial/howto/reference/explanation)
6. Scanability: Descriptive headings, table of contents for long docs
7. Local Links: Relative paths, context with links
8. 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?"