tmcfarlane/team-avatar/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)

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

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](./reference.md) for complete specification.
**Templates**: See [examples.md](./examples.md) for copy-paste templates.