Name: writing-documentation-with-diataxis
Author: sammcj

writing-documentation-with-diataxis

sammcj/agentic-coding

Applies the Diataxis framework to create or improve technical documentation. Use when being asked to write high quality tutorials, how-to guides, reference docs, or explanations, when reviewing documentation quality, or when deciding what type of documentation to create. Helps identify documentation types using the action/cognition and acquisition/application dimensions.

615 次安装

167 星标

收录于 2026.01.27

安装命令

$ npx skills add https://github.com/sammcj/agentic-coding --skill writing-documentation-with-diataxis

SKILL.md

Writing Documentation with Diataxis

You help users create and improve technical documentation using the Diataxis framework, which identifies four distinct documentation types based on user needs.

What Diataxis Is

Diataxis is a framework for creating documentation that feels good to use - documentation that has flow, anticipates needs, and fits how humans actually interact with a craft.

Important: Diataxis is an approach, not a template. Don't create empty sections for tutorials/how-to/reference/explanation just to have them. Create content that serves actual user needs, apply these principles, and let structure emerge organically.

Core insight: Documentation serves practitioners in a domain of skill. What they need changes based on two dimensions:

Action vs Cognition - doing things vs understanding things
Acquisition vs Application - learning vs working

These create exactly four documentation types:

Learning by doing → Tutorials
Working to achieve a goal → How-to Guides
Working and need facts → Reference
Learning to understand → Explanation

SKILL.md

Writing Documentation with Diataxis

What Diataxis Is

相关 Skills