writing-documentation-with-diataxis

The Diataxis framework structures documentation into four types—tutorials, how-to guides, reference, and explanations—each serving different user actions and cognitive stages. Align your content with whether users are learning, solving problems, or looking up facts to ensure clarity and usability.

Diataxis is a proven framework that organizes documentation by separating learning from problem-solving and action from understanding. It eliminates mixed content that confuses readers and ensures each page serves a single, clear purpose aligned with how users actually work.

Use the Diataxis compass to map content against two dimensions: action versus cognition (what users do versus understand) and acquisition versus application (learning new skills versus applying knowledge). This determines the correct documentation type and structure for your audience's immediate need.

Yes. Review messy or mixed documentation pages, identify which parts address learning, problem-solving, reference lookup, or conceptual understanding, then restructure and separate them into their appropriate Diataxis types using the framework's principles for language, flow, and review.

Diataxis provides detailed principles for each documentation type—clarity standards, language expectations, and structural patterns. Use these to review and guide authoring workflows, ensuring tutorials flow logically, how-to guides are task-focused, reference is scannable, and explanations build understanding.

Yes. Diataxis applies across products, APIs, and platforms. Analyze API documentation using the framework to separate getting-started tutorials, endpoint how-to guides, API reference pages, and conceptual explanations, improving usability for all user skill levels.