documenting-with-diataxis

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.

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.

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.

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.

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.