Epistemic Status: 
Blooming
A systematic framework for technical documentation authoring.
~ Diátaxis
Diátaxis is a system for thinking about how to write technical documentation. It divides up documentation into four main types.
- Tutorials
- How-to Guides
- Explanation
- Reference
This doesn’t imply a clean division between the different types. A tutorial can include explanation, but you often want to keep them separate because they serve different purposes. I’ve found it to be a useful way to approach writing technical documentation, even if what I write mostly falls into the Explanation type.
Not the only way
It’s not meant to be “the only way to do it”. Hillel Wayne has a good critique of Diátaxis and how it can be the wrong fit for some projects.
I summarize the four types as follows:
Tutorials
These are step-by-step guides that walk a beginner through a fixed project using the thing being documented. The important thing here is to give the user a sense of accomplishment at the end, so it’s critical that the tutorial always works. That is, as long as the user follows the steps laid out, they get to the end of it without any unforeseen problems.
It should take the user through the project from start to finish with no deviations beyond short asides that link to other documentation.
How-to Guides
These are step-by-step guides that remind an expert of the steps necessary to perform a fixed task. It is assumed that the reader knows how to do the task, and the how-to guide exists solely to make sure they don’t make a mistake or miss an important step.
Thoughts on How-to Guides
My feeling on how-to guides for software projects is that they are an indication that the thing you’re documenting is too complex, or convoluted. A step-by-step guide to a regular task screams “automate me” at me, e.g. wrapping project setup steps into a Nix dev shell. This may not always be possible though.
Explanation
Explanations go into the why of a thing. These are deep dives into a topic, with no goal of guiding someone through setting up something new, or something they’ve done before.
I find these easier to write actually, even though the author of the Diátaxis website says they can be the hardest to write. For me these take the form of a story most often, or a dialog. I’m not sure how effective mine actually are since I haven’t gotten much feedback directly on things like this that I’ve written in the past.
Reference
Reference guides are for describing as clearly as possible the details of a subject. The needs that drive it come from the thing it’s describing and not so much the user of the reference guide.
I think most people understand what reference is. It’s the auto-generated documentation you get from things like cargo doccargo doc or mix docsmix docs (assuming you wrote it in the code, you do comment your code, right?).
Having this be something that’s easy to link to makes writing the other types of documentation easier, because they can link to the reference.
For more details on Diátaxis, go visit the website. The author has a lot more to say about each, but it’s also a pretty quick read.