Why it matters

Bad docs cost engineering time constantly. Good docs are a force multiplier. Understanding what makes docs useful is worth learning.

Advertisement

The architecture

Diátaxis framework: four doc types by purpose. Tutorials (learn), how-to guides (do), reference (find), explanation (understand).

Documentation typesTutoriallearn by doingHow-totask recipeReferenceauthoritative factsDifferent content structures serve different reader modes; mixing them confuses
Diátaxis quadrants.
Advertisement

How it works end to end

Tutorial: walk beginner through a scenario. Complete, working, hand-held.

How-to: task-focused steps. Assumes knowledge; solves specific problem.

Reference: exhaustive, precise, findable via search.

Explanation: context, design decisions, background.