[cbsmith]

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.

[SideburnsOfDoom]

> 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.

[cbsmith]

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.