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?"

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.