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