What is it?
A systematic approach to technical documentation authoring.
TL;DR: Make the technical documentation you’re writing more effective by focusing on its purpose.
The four types of documentation
- Tutorials are for guiding the reader through a hands-on experience to learn the subject
- How-to guides are directions the reader can follow to accomplish a goal (think recipe book)
- Reference documents are technical descriptions of the parts of a system (think API reference)
- Explanations give the reader less directly-applicable—though still important—knowledge about the system, often discussing the why behind it
My thoughts on the framework
It’s brilliant.
Coupled with Google’s Technical Writing Course, and you’ve got yourself a solid foundation for writing excellent technical docs. By having a clear focus on your audience and why they’re reading this particular document, you can make your docs actually useful.
The system can be applied on an existing documentation base without the need for an overhaul, so it’s an easy win to start writing new docs using this framework at any point in a project or system’s lifecycle.
User journey
You can think of Diataxis as a framework for writing documentation for different stages in a user’s journey through learning and using your system. For those who are just getting started, they’ll want tutorials to hold their hands and guide them through the first steps. After that, they’ll want how-to guides to accomplish specific goals. At this point, they’ll need to be able to find the specific goal that they’re looking for (see also How to Design Services that Work), like finding the right recipe in a book.
When they branch out and start using your system in a way that isn’t explicitly laid out in a tutorial or how-to guide, they’ll need a reference of some sort to understand how the machinery works. After a while, they may start to wonder why you built it in this specific way. This is when explanations are useful. ADRs are a great example of these.