Write the Docs Prague 2017: What nobody tells you about documentation by Daniele Procida

Documentation isn’t a single thing—it’s four distinct kinds of material that serve different jobs in a user’s journey. When teams mix those jobs together, documentation becomes harder to write, harder to maintain, and less useful; when they keep the four functions separate, the whole project becomes easier to navigate and more likely to win real users.

Daniele Procida frames the stakes bluntly: even strong software often fails to gain adoption when documentation is missing or “just good enough.” Users won’t be forced to learn a tool that feels like extra work, and the free-choice reality of open source means people will move on if the documentation doesn’t help them succeed quickly. The common problem isn’t that teams aren’t trying hard—it’s that they’re trying to write documentation in the wrong way, without matching content to the specific learning or reference need it’s supposed to satisfy.

The core prescription is a four-part model. First are tutorials: teacher-led, step-by-step learning experiences that “take the reader by the hand” and produce immediate, repeatable wins. Tutorials should be concrete and action-based, designed to build confidence and momentum rather than to deliver abstract explanations. Their job is to start beginners on a path that makes the rest of the documentation and the software itself feel coherent.

Second are how-to guides: answer-driven, task-oriented instructions that help users complete a specific goal. Unlike tutorials, how-to guides can assume some baseline competence and can be more flexible—showing how to apply steps in slightly different contexts. The guiding principle is usability over completeness: the reader needs to get to an outcome, not wade through options or theory.

Third are reference guides: technical descriptions of the “machinery” such as classes, functions, fields, and APIs. Reference material should be austere and accurate—focused on what exists and how it’s structured—using examples only to illustrate usage. It must mirror the domain and the codebase’s structure so readers can find information reliably.

Fourth are explanations: discussions that clarify concepts and provide background, connections, and alternative perspectives. Explanations help users step back from the details and understand why things work, how ideas relate, and what assumptions underlie the system. They’re not meant to replace instruction or reference; they complement them by deepening understanding.

Procida argues that the four categories naturally pull against each other inside typical software documentation workflows. Teams often store everything in the same repository, deliver it through the same channels, and even write it with the same tools and by the same people—blurring the boundaries. Internal tensions also exist: tutorials and how-to guides both deal with practical steps, while explanations and reference material both relate more to theoretical knowledge. The result is “quadrants” that bleed into one another.

The fix is to enforce separation so each piece has one clear job. He points to Django documentation as an example where topic guides explicitly spell out explanations, and where the documentation is organized into distinct sections that map to the four functions. The payoff is practical: documentation becomes easier to maintain because authors know what belongs where, and users get the right kind of help at each phase—learning, doing, looking up, and understanding—without forcing one format to do the work of another.