Comment by Nathanba
2 years ago
I don't agree with it because while I think that it's theoretically correct, the words are too close together. To me "tutorial", "how to guide" and "explanation" are all practically synonyms. I know that when you think deeply about it, there are legitimate reasons for each category but it's just too close semantically that my brain can't see the difference. If I want to know how something works and I see "tutorial" and "how to guide" I have no idea what to click and I just click on the first thing.
>the words are too close together. To me "tutorial", "how to guide" and "explanation" are all practically synonyms.
If that set of labels doesn't work for you, there are many other ways that the Diataxis doc attempts to explain the differences. You might find it a useful exercise to seek terms that make more sense to you. Or just to try to understand them in other ways - e.g. via the action/cognition ("do vs. think") and acquisition/application ("at study vs. at work") dichotomies.
There's an entire page devoted to distinguishing tutorials from how-to guides (https://diataxis.fr/tutorials-how-to/). (Note that this is itself classified as "understanding" material; as an exercise, you could try to evaluate the writing there to see how it maps onto what is described as "explanation", and doesn't map onto how a "tutorial" is supposed to work.)
But to me, one of the simplest distinctions is that a "tutorial" is the sort of thing that you can't do on Stack Overflow. That's because a tutorial involves following a lesson plan that was set by a teacher, who fills in the student's unknown unknowns. On Stack Overflow you must ask a question; a tutorial is material for someone who doesn't yet know what to ask.
There are plenty of extraordinarily popular questions on Stack Overflow that ask how to do some simple task. But to work in the format, you have to ask, not simply request help (see also: https://meta.stackoverflow.com/questions/284236).
Can you see the problem though: If you need a huge page dedicated to explaining the difference between how-tos and tutorials then it's clearly too confusing and not obvious at all. Nobody is going to need a page telling them the difference between sample code and documentation. Those two words are obvious even though yes, sample code is of course also documentation in a sense.
It all seems close because the terms are muddied in our minds by countless poor instructions over the years.
Their doc actually explains the difference efficiently though :
Tutorials - learning-oriented experiences
How-to guides - goal-oriented directions
Reference - information-oriented technical description
Explanation - understanding-oriented discussion
But I want to learn something in all of those examples. I have a goal in all I do. I need technical information in all as well and I want to gain understanding in all of those as well. It really is just a bad way to name these categories. I haven't thought about how to do it better yet, I personally like the ziglang docs where everything is presented as a huge reference document with examples in each section. The only additional thing that is needed is usually something like APIs and executable code. Of course the reference document can also have executable samples like what Stripe does. But somehow I think a dedicated section for example code is legitimate in addition to a long reference.
I think they wanted to separate out four different concepts in the territory, needed a name for each one, and so picked four almost-synonyms for the labels on the map. We can read "tutorial" in their system as a technical term rather than its everyday meaning, just as "depression" has a particular meaning to a psychologist that might not match everyday use.
I guess that's still better than labelling them Type I-IV tutorials.
Are they really so close?
The lecture is the explanation. The tutorial/lab is a guided experience (Microsoft's fake Contoso company comes to mind). A how-to guide is what you need when you want to search/chatgpt a solution. Reference material: thesaurus, encyclopedia, owner's manual.
Video games have built-in tutorials and yet walkthrough guides are still necessary for tricky puzzles. You check the key bindings as reference.
Your videogame example shows the problem. Tutorials are effectively just a different form of walkthrough. You are getting walked through the basics. So that's my point, you can't have different words on your website that is supposed to help people gain understanding and then start off by confusing everyone with words that are all so close in meaning.
The purpose is always the same: To learn. It's how you learn and what your learn for that are different. A tutorial is for getting exposed to something. A guide is for a very specific purpose in something you're already familiar with. An explanation is for a deeper understanding and references are for not relying on memory. They all refer to different things that ultimately falls under the same concept (and intersect with each other). If you're building a system, you should have all of them otherwise, the documentation is lacking.
> "tutorials are just a different form of walkthrough"
Yes, one is focused on understanding (mechanics, lore, UI) and the other is focused on a specific task (do these steps to progress).
Diataxis is not inventing these words - it is using them deliberately. You seem unwilling to actually [learn what they mean](https://chatgpt.com/share/6751d9b7-3fd4-800a-8b81-1949069007...).
You also need good writers who by example make it perfectly clear what's what.
how-to is for configurations. tutorial is for orientation. explanation is for models.