documentation-writing_skill

Overview

This skill produces clear, discoverable software documentation following the Eight Rules and the Diataxis framework. It enforces placement in docs/, requires linking and runnable examples, and structures files by purpose so users can find the right content quickly. Use it to create READMEs, API docs, tutorials, how-tos, and reference pages that are consistent and testable.

How this skill works

The skill inspects your repository and ensures all documentation files live under docs/ with one Diataxis type per file (tutorial, how-to, reference, explanation). It validates that each document is linked from an index or parent doc, uses relative links, contains runnable code examples, and omits temporal or status content. It can generate templates, add entries to docs/index.md, and produce a final checklist to validate currency, scanability, and example execution.

When to use it

• Creating a new README or project overview
• Writing API reference pages or configuration docs
• Authoring tutorials or step-by-step how-tos
• Converting ad-hoc notes into discoverable docs under docs/
• Validating documentation before release or pull request

Best practices

• Place every doc in the appropriate docs/ subfolder (tutorials, howto, reference, concepts)
• Follow Diataxis: one purpose per file and make the user question clear up front
• Include short Quick Start with 3–5 steps and at least one runnable example
• Use descriptive headings, a table of contents for long pages, and relative links
• Avoid temporal content; put progress, tests, and decisions in Issues/CI/commits

Example use cases

• Generate a README with Quick Start, Configuration, Usage, and Troubleshooting sections and add it to docs/index.md
• Turn a feature spec into a How-To with runnable code snippets and configuration examples
• Create an API reference page with examples that run in CI and link back to tutorials
• Convert a large explainer into a concise concepts page and link to related how-tos and references