The biggest problem I see when looking at material to be learned, whether technical documentation, tutorials, or other reading materials, is that they jump straight into the worked explanations of what is happening, and assume a reasonable knowledge of the surrounding material. This is bad.
For example, who remembers learning calculus? The first thing that 99% of schools will teach is how you do differentiation. Differentiation is a fine starting point for basic calculus since it is the lowest building block on which the subject is built, beyond simpler forms of maths. The problem is starting with “how” to do something rather than the “why”. Without at least a basic intuition for what differentiation (or any other subject) means and why it would be used, it becomes a much more abstract concept. Fair enough, it is an abstract concept but it’s one we apply to every day life. No-one, in the real world, cares about the quadratics it is applied to until those quadratics are modelling some very concrete problem.
Before a single example or “how” is shown in any documentation, you need to reinforce the “why”. Not only does it make the concept clear and applicable, giving a more physical and understandable notion of what is happening, it gives a goal to work towards: how to actually do the real world examples given.
This approach translates far better to being able to then problem solve using the same tools (like differentiation) in other areas, because the student has a feel for the subject.