Why Diátaxis Gets Mistaken for Four Folders — And Why Two Modes in One Page Collapse

• If you have ever opened a tutorial and closed the tab thirty minutes later
• Creating four folders is not adoption
• The reason there are four is that there are two axes
• The compass — asking two questions of a single paragraph
• The most common confusion happens between tutorial and how-to
• The two states demand opposite things
• The path by which explanation seeps into reference
• What you can do this week — one paragraph, one commit
• Summary and sources

If you have ever opened a tutorial and closed the tab thirty minutes later

Suppose you open the official tutorial for a library you are using for the first time. Item 1 has you install it. Item 2 has you run the example. So far so good. Then item 3 suddenly begins with "this value can be configured in three ways, and in production the second is recommended." You are handed three options while you have no idea which of the three to pick. Item 4 brings two paragraphs on internal mechanics, and item 5 returns to commands.

This document contains no false information. The sentences are perfectly fine. And yet the reader closes the tab after about thirty minutes. The route by which the documentation team learns this is usually feedback saying "the docs are lacking," and what they do after receiving that feedback is usually to add more content. Then the next person closes the tab after twenty-five minutes.

Creating four folders is not adoption

What named this problem is Diátaxis. It divides documentation into four kinds: tutorial, how-to guide, reference, and explanation. It is widely known and widely cited, but adoption in an actual team generally stops right here. Create four folders in the docs repository, move the existing documents under them, done.

Yet the people who made the framework explicitly warn against this approach. The Diátaxis workflow document says you do not need to divide your documentation into four sections when you start, and it nails the point down about creating four empty sections with nothing in them: do not. Structure is something that appears later as a result of improvement, not something imposed first in order to improve. The author expresses this by saying Diátaxis changes the structure of documentation from the inside out.

The reason there are four is that there are two axes

Why exactly four matters. If there is no reason it is not three or five, then this is merely a convenient classification, and a convenient classification is no help at all in front of an ambiguous document.

The foundational Diátaxis document places the person using a skill on two axes. One is action versus cognition. Any skill has both practical knowledge about what to do and theoretical knowledge about what is true. The other is acquisition versus application. A person is either in the middle of acquiring a skill, or in the middle of using a skill already acquired. You can restate that as the studying state and the working state.

Since the two axes are independent, there are necessarily four quadrants. The need to learn is served by the tutorial, the need to accomplish a goal by the how-to, the need for information by reference, and the need to understand by explanation. Four is not an arbitrarily chosen number; it is the minimum count that covers the territory without remainder.

The compass — asking two questions of a single paragraph

The map is easy to remember, but in front of an ambiguous document intuition is frequently wrong. So Diátaxis provides a separate decision table called the compass. There are only two things to ask.

The important thing is that this table can be used at the paragraph level, not just at the document level. In fact Diátaxis recommends applying it down to the level of sentences and words. Put item 3 of the tutorial we saw earlier into this table and the answer comes out immediately. The part listing three configuration methods addresses cognition and faces a person who is working, so it is reference. The rationale for the production recommendation is cognition facing a person who is studying, so it is explanation. Three modes were living inside one document.

The most common confusion happens between tutorial and how-to

Diátaxis points out that the most common confusion in software documentation is the confusion between tutorial and how-to. The reason is simple: the two look almost identical. Both present numbered steps, both promise success if you follow them in order, and both are useless to a reader who does not move their hands.

The difference is not in the form but in the need being served. A tutorial serves someone who is studying; a how-to serves someone who is working. A second misconception that often comes up here is the split where tutorials are basic and how-to guides are advanced, and this is wrong too. The original text says a how-to can and should cover elementary procedures, and conversely that a demanding tutorial for a highly skilled person is possible. The dividing line is not difficulty but whether the reader is studying or working.

The two states demand opposite things

This is where the reason mixing collapses comes from. What the two states demand is mutually exclusive.

• Choices: a tutorial does not create forks. Give options to someone who is not yet able to choose and they stop right there. Conversely a how-to must branch. Reality has varied conditions, and a guide with no branches by condition is useless in the field.
• Responsibility: if something goes wrong in a tutorial, that is the author's fault. You must have controlled the environment so the learner cannot fail. In a how-to, the user is responsible for their own situation.
• Safety: a tutorial must let you return to the beginning at any time. A how-to cannot make that guarantee. Work that has to be got right the first time is common.
• Explanation: Diátaxis says flatly that a tutorial is not the place to explain. It adds that the urge to tell people why is the hardest temptation for a teacher to resist. Borrowing the original wording, the first rule of teaching is "don't try to teach."

So the moment you put options into item 3 of a tutorial, that document gets worse for both readers. It forces a decision on the person studying, and it does not even show all the branches the person working needs.

The path by which explanation seeps into reference

The same thing happens between the other two modes, and on this side it is far quieter. Diátaxis traces the path concretely. Putting examples into reference is legitimate in itself. The problem is that examples are fun, and as you write them you keep spreading into why it comes out this way and what happens if you do it that way.

The result is a loss on both sides. The reference becomes hard to search because it is buried in detours, and the explanation cannot unfold properly because it is lodging in someone else's house. The criterion is once again a single one: is this something you open in the middle of doing the work, or something you need when you step back from the work to think?

There is also a good rule of thumb for when you cannot tell reference from explanation. If it is boring and does not stick in the memory, it is probably reference, and things that organize into lists and tables are usually reference too. Conversely, if it is the kind of thing that would make a good answer if someone asked you while out on a walk, it is explanation.

What you can do this week — one paragraph, one commit

The Diátaxis way of working is on the side of not drawing the big picture. Instead of making a plan and moving everything at once, it says to repeat these four steps.

1. Pick anything. Do not go hunting for problems; look at the file that is open right now, the page you just read. If there is nothing, pick at random.
2. Weigh it up. Smaller than a page is better. One paragraph, or even one sentence, is fine. What need is this for, how well does it fill that need, and what could be added, moved, or deleted to make it better?
3. Choose exactly one thing. Pick the single next action that constitutes an improvement right now.
4. Do it and be done. Do that one thing and commit or deploy right away. Do not feel you have to do more.

If you bring it into your own team, you could start like this. Open the single document that was opened the most this week, and put the compass questions above to every paragraph, tagging each one. If a document ends up with more than one kind of tag, pick just one of them, move it into another document, and leave only a link where it was. If the document to move it into does not exist yet, do not create an empty folder — create one document. This difference is exactly where you avoid the mistake that was warned against earlier.

The fact that documentation never ends does not change. Diátaxis likens documentation to a growing plant, saying that it is never finished but can be complete at every stage. A document where you moved a single paragraph this week is complete in that state.

Summary and sources

Reduced to one line: Diátaxis is not a rule for classifying documents but a rule for asking whose state, and which state, a single piece of writing serves. Four folders will not ask that question for you.

• The official Diátaxis site — the framework itself. Every item below is a document on this site.
• Foundations — action and cognition, acquisition and application, the two axes, and why there are four quadrants
• The compass — the table that decides with two questions
• The difference between a tutorial and how-to guide — the contrasts on choices, responsibility, safety, and explanation, and the basic-versus-advanced misconception
• The difference between reference and explanation — the path by which explanation seeps into reference, and the rule of thumb
• Diátaxis as a guide to work — the warning against creating empty sections, the four-step work loop, the distinction between complete and finished
• Tutorials — the principle of not trying to teach, and explanation as a temptation
• The source text can be read as-is in the evildmp/diataxis-documentation-framework repository. The quotations and summaries in this post were confirmed directly against the originals in that repository.