Agent skill · writing content · sammcj
writing-documentation-with-diataxis
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.
Why this skill is useful
Provides a structured framework for creating documentation that enhances clarity and usability, which the AI may not generate independently.
What it needs
About 5k tokens when loaded. Last updated 2026-08-07. 154 stars on the source repository.
What this skill does
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: 1. Action vs Cognition - doing things vs understanding things 2. 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 Why exactly four: These aren't arbitrary categories. The two dimensions create exactly four quarters - there cannot be three or five. This is the complete territory of what documentation must cover. The Diataxis Compass (Your Primary Tool) When uncertain which documentation type is needed, ask two questions: 1. Does the content inform ACTION or COGNITION? Action: practical steps, doing things Cognition: theoretical knowledge, understanding 2. Does it serve ACQUISITION or APPLICATION of skill? Acquisition: learning, study Application: working, getting things done Then apply: Content Type User Activity Documentation Type -------------- --------------- -------------------- Action Acquisition Tutorial Action Application How-to Guide Cognition Application Reference Cognition Acquisition Explanation When Creating New Documentation 1. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills sammcj/diataxis-documentation