Why your docs frustrate people (and the 4-box fix)

Most documentation feels messy because it mixes four incompatible jobs into one blob. A frustrated beginner wanting a gentle walkthrough lands on a dense API reference; an expert hunting one detail has to wade through a beginner story. The Diátaxis framework says good docs serve four distinct needs, and you should never blend them.

The four types are: tutorials (learning-oriented — a hand-held lesson that gets a newcomer to a first win), how-to guides (task-oriented — recipes to solve a specific real-world problem), reference (information-oriented — dry, complete technical facts like function signatures), and explanation (understanding-oriented — the background and why behind design choices).

The key insight is a two-axis map: some docs serve learning vs doing, and some serve practical steps vs theoretical understanding. A tutorial teaches while you act; reference informs while you work; explanation deepens understanding while you study. Mixing them is why so many projects have docs nobody enjoys.

You don't need to write all four at once. Just labeling each page by its purpose — "is this teaching, or is this a lookup?" — instantly makes documentation easier to navigate and far less frustrating to read.