skills.rest
abatilo
abatiloCOMMUNITY
Explore all skills by this author →
Website𝕏@aaronbatiloGitHub

diataxis-documentation

Generate Diataxis-compliant documentation covering tutorials, how-to guides, explanations, and references.

10|2|Updated Sep 28, 2015
Search Tags:#documentation#technical writing#reference#explanation#tutorials#how-to guides#diataxis
One-click install
npx skills add https://github.com/abatilo/vimrc --skill diataxis-documentation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: diataxis-documentation
Source: https://github.com/abatilo/vimrc/tree/main/skills/diataxis-documentation
Command: npx skills add https://github.com/abatilo/vimrc --skill diataxis-documentation

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Poorly organized or unclear documentation frustrates users and wastes time. This skill helps you create high-quality, user-focused documentation by applying the Diataxis framework, ensuring each piece of content serves a specific user need (tutorial, how-to, reference, explanation).

Core Features & Use Cases

  • Documentation Type Identification: Guides you to correctly classify content as a tutorial, how-to guide, reference, or explanation based on user context and content nature.
  • Best Practice Application: Provides detailed guidelines for structuring, writing, and styling each documentation type, ensuring clarity and effectiveness.
  • Iterative Improvement Workflow: Supports continuous, small-scale enhancements to existing documentation, making quality improvement manageable and immediate.
  • Use Case: You need to write a "Getting Started" guide for a new feature. Use this skill to identify it as a "Tutorial," then load the specific reference to ensure it focuses on learning by doing, provides immediate success, and avoids over-explanation.

Quick Start

Use the diataxis-documentation skill to help me write a "How to deploy to production" guide, ensuring it follows best practices for how-to guides.

Frequently Asked Questions about diataxis-documentation

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

FAQPage Schema
What is the Diataxis framework and how does it improve documentation?▼

Diataxis is a documentation framework that organizes content into four types—tutorials, how-to guides, explanations, and references—each serving a specific user need. It improves documentation by ensuring clarity, reducing user frustration, and making content discoverable by matching the right information type to the user's task or learning stage.

How do I identify whether content should be a tutorial, how-to guide, explanation, or reference?▼

Tutorials teach through doing and deliver immediate success; how-to guides solve specific problems with focused steps; explanations build conceptual understanding; references provide lookup data. Choose based on user intent: learning by doing (tutorial), solving a concrete task (how-to), understanding why (explanation), or finding facts (reference).

How do I structure a how-to guide for clarity and effectiveness?▼

A how-to guide focuses on concrete steps to solve a real problem. Start with prerequisites, use numbered steps with clear context, avoid over-explanation, and assume the reader knows the basics. Each step should move toward the goal without digression into conceptual detail.

Can I use Diataxis to organize and improve existing documentation?▼

Yes. Diataxis supports iterative content improvement by letting you audit existing docs against the four types, reorganize scattered content into their proper categories, and incrementally enhance each section. This makes quality improvement manageable without requiring a complete rewrite.

What's the difference between a how-to guide and an explanation in technical writing?▼

A how-to guide provides steps to accomplish a specific task; an explanation builds understanding of concepts, mechanisms, or reasoning. How-tos are action-oriented; explanations are knowledge-oriented. Use explanations when users need to understand the 'why' before or alongside the 'how'.

When should I use reference documentation instead of tutorials or guides?▼

Use reference documentation for lookup-driven content: API parameters, command options, configuration keys, or data structures. Reference is fact-dense and scannable, not narrative. Use it when users already understand the concept and need specific details quickly.

Related Skills

Explore More Content & Communication Skills→
m00spm00sp

documentation-writer

Create structured technical documentation using the Diátaxis framework.

Community
Intermediate
grasberggrasberg
3

technical-writer

Organize software documentation into Diataxis tutorials, how-tos, references, and explanations.

Community
Advanced
ChristopherAlphonseChristopherAlphonse
1

documentation-writer

Generate Diátaxis-style documentation with tutorials, guides, reference, and explanations.

Community
Advanced
Giskard-AIGiskard-AI
3

diataxis-documentation

Classifies technical documentation into Diataxis-based types and improves clarity.

Official
Advanced