diataxis

The Diátaxis framework structures technical documentation into four types: tutorials, how-to guides, reference, and explanation. This approach aligns content with user needs by categorizing documentation based on whether users are studying, working, finding information, or understanding.

You can classify existing documentation using a compass-based decision guide. It evaluates the content's purpose and assigns it to one of the four Diátaxis types, ensuring each document aligns with the correct user need and documentation strategy.

No, you do not need to overhaul your entire documentation structure at once. The Diátaxis framework supports an incremental improvement approach, allowing content teams to classify and restructure documents gradually without disrupting existing software project documentation.

The compass categorizes content by loading guidance from reference files and applying frontmatter-driven metadata. It consistently sorts technical writing into tutorials, how-to guides, reference, or explanation based on the document's core purpose and target audience needs.

Use a how-to guide when the user needs to accomplish a specific task and already knows the basics, whereas tutorials are for learning. The compass helps classify these documents correctly by evaluating whether the goal is practical application or foundational learning.