documenting-with-diataxis

Classify documentation topics into Diataxis types and apply matching templates.

Updated Aug 23, 2026

Search Tags:#documentation #writing #reference #how-to #explanation #tutorial #diataxis

Ready to run

npx skills add https://github.com/cyarie/cyarie-claude-plugin --skill documenting-with-diataxis

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: documenting-with-diataxis
Source: https://github.com/cyarie/cyarie-claude-plugin/tree/main/skills/documenting-with-diataxis
Command: npx skills add https://github.com/cyarie/cyarie-claude-plugin --skill documenting-with-diataxis

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Documentation often mixes different types (tutorials, how-tos, references, explanations) leading to unclear outcomes. This skill ensures topics are classified according to the Diataxis framework to guide appropriate writing and preserve clarity.

Core Features & Use Cases

Type identification: classify a topic into one of the four Diataxis types based on user need.
Writing templates: provide structure guidance and tone for Tutorial, How-to, Reference, and Explanation.
Documentation audit: assess existing content for alignment with Diataxis and suggest reorganization.
Use case: when documenting a new API, determine whether to create a Reference for lookup, a Tutorial for onboarding, a How-to for common tasks, or an Explanation for rationale.

Quick Start

Draft your topic as one of the four Diataxis types by analyzing user needs and selecting the appropriate document type.

Frequently Asked Questions about documenting-with-diataxis

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

What is the Diataxis framework for software documentation?▼

The Diataxis framework classifies software documentation into four types: tutorials, how-to guides, references, and explanations. It guides writers to match document structure with user needs, preventing mixed formats and ensuring clear outcomes.

How do I classify a topic into the correct documentation type?▼

You classify a topic by analyzing user needs: learning needs tutorials, achieving tasks needs how-tos, information lookup needs references, and understanding rationale needs explanations. This skill applies consistent type identification to guide appropriate writing.

How do I audit existing documentation for Diataxis alignment?▼

You audit existing documentation by assessing content against the Diataxis framework to identify mixed formats. This skill evaluates alignment and suggests reorganization to separate tutorials, how-tos, references, and explanations for clarity.

What's the best way to structure an API reference versus a tutorial?▼

Structure an API reference for information lookup with dry facts, while structure a tutorial for onboarding with learning-oriented steps. This skill provides specific writing templates to enforce appropriate tone and structure for each type.

Why does mixing tutorials and explanations make software documentation unclear?▼

Mixing tutorials and explanations creates unclear outcomes because it combines learning steps with theoretical rationale. Diataxis prevents this by applying checks to separate documentation formats, preserving the distinct purpose of each type.