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
• Usage
• 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 - 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

# [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 for complete specification. Templates: See examples.md for copy-paste templates.