I always want to jump right to the explanation documentation. The rest of it seems like a waste of time (well, the Reference bit can be somewhat useful later). I find tutorials and HOWTOs as misleading at best.
Well, that's your preference, it's definitely not everyone's. But you too would benefit from the explanation documentation being clearly labelled as such, so you can go there and avoid tutorials.
In hindsight, I realize my tone was off in that comment. I didn't mean it like it was the right choice or that there was anything wrong with Diátaxis. Since people find it helpful I presumed it was... and you're absolutely right about the clear labeling! This article was a really helpful insight for me.
I just hadn't really appreciated why other people wanted different kinds of documentation. I always feel like if I don't understand the "why" I really don't know the tool and therefore shouldn't use it until that was addressed.
> I always feel like if I don't understand the "why" I really don't know the tool
What I find for me, and what I think is really common, is that a longwinded "why" is not the right place to start - it's too dry, not practical, and I can bounce off it without understanding.
Starting with a demo, a "you can use this tool to do xyx in 5 lines of code, here's how" makes me see that it has value, to get a basic feel for it. And once that is in place I get that it has value - it's like a hook to hang the "explanation" on.
Then the reference is useful later, when you're somewhat familiar, but need to check a specific thing that you don't know yet. You don't need or want to read a long multi-paragraph explanation to confirm a technical "yes or no" question.
Yeah, if I'm reading documentation to decide if there's a value proposition worth exploring, I've already made a mistake. You've got a make the value proposition, and then I'll read about the "why" to understand if that value proposition can be realized. Why would I read a tutorial or a HOWTO for something with no known value?
The reference is relevant to me too, though modern information retrieval tools make it much less so, as I can often get the reference information I want in context. The main reason the reference is helpful is that explanations often aren't as precise as you need them to be about the specifications for the tool.
In retrospect, I do get some value out of tutorials & HOWTOs, mostly as a check on my understanding. They're just not where I want to start.
I think a good way of framing it is that a lot of documentation these days starts with "getting started", and I've observed that more often than not, that actually makes everything more difficult. If I understand the tool first, I avoid going down a lot of blind alleys and misinterpretations. I have observed that people often use a tutorial or a HOWTO as a way to get something done quickly without ever reaching that understanding, but the reality is the understanding is reason you wanted a human using the tool in the first place.
If I'm in a rush to achieve a goal, using a new tool is going to slow me down, with or without a tutorial. I consequently find the tutorial of limited value and usually just something I scan through until I get to the "real" documentation. It's revelatory how this works for other people. I guess I always understood that, but didn't really "grok" it until now.
And tutorials give you an overview of how simple/complex something is to achieve, which may be just what you need before deciding to spend more time on the rest of the documentation.
If the “Hello World” tutorial for a new language takes 3 hours and downloading 15 GBs of files before you can start, maybe you’ll look at something else.