Further it's explained that this is where the "understanding" bit comes in. Ugh, so this school of thought is where some of the terrible modern documentation comes from...
I want the explanations/understanding first COMBINED with a minimal how-to guide serving as illustration for the explanation.
Then a quick link to an API reference that INCLUDES snippets of explanations and usage examples (that you'd find in tutorials or how-to guides).
Separating thinking about documentation this way leads to horrible documentation where you start with dumbed-down tutorials missing lots of crucial information, and then you have to put in tons of unnecessary effort putting disparate things toget ther in your head. FFS, programmers are rarely students since most of what we learn is learning-on-the-job and never chefs or theoreticians. Tutorials always waste your time so you'd prefer to start with something much denser... only that the only thing denser you easily find are the API docs, and you lack the explanations to understand them and usage exmaples so you have to hunt them for yourself... yuck.
As an example of GREAT documentation that combines things well (the API docs contain concise math theory / formular / explanations AND usage examples), take a look at some of the Pytorch docs: https://pytorch.org/docs/stable/generated/torch.nn.Conv2d.ht...