documentation

Diataxis documentation separates content into four distinct types—tutorials, how-to guides, reference, and explanation—each with specific purposes and principles. Load the relevant reference file for your documentation type to apply its guidance, ensuring your content serves its intended user goal and follows consistent structural patterns.

Tutorials teach by doing and build confidence; how-to guides solve specific problems step-by-step; reference provides facts and specifications for lookup; explanation builds understanding through context and narrative. Each type serves a different user need and requires distinct writing patterns and organization.

Review documentation to verify it adheres to its declared type by loading the type-specific reference guidance, then checking whether structure, tone, examples, and goals align with Diataxis principles. Misclassified content should be reorganized or rewritten to match its intended purpose.

Mixing documentation types within a single document creates confusion because each type optimizes for different user goals and reading patterns. Keep each type separate and link between them; use the type-specific reference guidance to ensure boundaries are clear.

Before writing, identify which documentation type—tutorial, how-to guide, reference, or explanation—fits your user's goal, then load its corresponding reference file to understand its specific principles, structure, and patterns before drafting.

Diataxis principles apply across domains because they address how users learn and retrieve information regardless of subject matter. The four types—tutorials, how-to guides, reference, explanation—work for any field; load the relevant reference to adapt the framework to your context.