Structuring documentation with Diátaxis

Goal

Make documentation findable and usable by giving each page one purpose and one reader situation.

Prerequisites

Existing documentation, however messy, and a list of the questions users actually ask.

Steps

1. Classify each existing page or section into one of four quadrants: tutorial (a lesson that takes a beginner through a complete, safe experience), how-to guide (steps to achieve a specific goal for a competent user), reference (accurate, complete description of the machinery), explanation (discussion of context, design and trade-offs).
2. Split pages that mix quadrants; a reference page should not teach, a tutorial should not explain every option.
3. Name and organise the navigation by quadrant so that readers can find "how do I…" separately from "what does X mean".
4. Write reference from the code where possible (generated API schemas, command help) and keep it exhaustive; write how-to guides from real tasks and keep them short.
5. Review new documentation against the quadrant it claims.

Expected result

Readers land on the page type that matches their need; maintainers know where a new piece of information belongs.

Limits and test basis

Small projects may need only reference and one how-to guide; the framework is a map, not a quota. The four categories follow the cited framework.