Diátaxis
A documentation framework that separates learning, tasks, facts, and understanding into tutorial, how-to, reference, and explanation.
See it
What it is
Diátaxis is Daniele Procida's framework for separating documentation into four modes. Tutorials help a learner acquire skills, how-to guides help someone complete a task, reference supplies exact facts, and explanation builds understanding. Each mode serves a different reader need.
Reach for it when one document is trying to teach, troubleshoot, list every option, and explain the theory at once. Classify the reader's immediate need, split mixed pages, then give each mode the structure it deserves: a guided path, numbered task steps, scannable facts, or connected reasoning.
Gotcha: the four modes are not a publishing sequence or four headings to force onto every topic. A tutorial can link to reference, and a how-to can include one necessary explanation. The failure is letting the secondary material take over the page's main job.
Ask AI for it
Restructure these docs with the Diátaxis framework. Classify every section as tutorial, how-to guide, reference, or explanation; flag sections mixing more than one mode; then produce four separate outlines. Give tutorials a guided learning path, how-to guides numbered steps toward one goal, reference exhaustive scannable facts, and explanation a concept-led narrative. Preserve every factual detail and add explicit cross-links where one mode depends on another. Finish with the proposed file tree and a Docusaurus sidebars.js entry with one category per mode.