>the idea that you start with a language level that is missing capabilities so that you directly experience the problem and then understand the motivation for the additional complexity of the next level.
This is how I want documentation written for features added to a language.
For example, why were arrow functions added to JavaScript? The documentation should explain the problem and motivation for why it was added to the language with demo code so someone can directly experience the problem.
I want this for every single feature added after the 1.0 release. Not just for JS, but for every language, library, and framework.
This is commonly referred to as a "rationale" document. It exists for some languages, but not all, and helps to establish both why something has been done and why something else has not.
That is the Ada 2012 Rationale, for example. It details changes to the language standard with examples and explanations, as well (in the Epilogue sections) as things that were dropped. It would definitely be nice to have this for more languages, especially as it can help you grok what's changed in a specific version/edition/whatever (not just a full Language X rationale, but Language X 2.0's rationale for changes over Language X 1.0).
I pretty much never use Python. I've false started on getting into it a couple times, but never quite got enough fun or dollars out of it to stick with it.
That said, whenever an interesting or controversial PEP starts making the rounds in forums like this one, I almost always wind up reading the whole thing on account of how well thought-out they are.
I try to do something this when I'm teaching classes. Do the "why should I listen to this? What's it going to get me?" bit right at the start.
Give some examples so folks can decide if it's relevant to them, then show them how to do it (with follow-along coding or a hands-on lab if at all possible), and only at the end dive into how it works.
That way, even if people zone out partway through, they may have learned something useful.
Last time I tried introduction to programming classes I introduced concepts in the following order: variables (store results!), if-else (actually get interesting results!), then arrays (lists of variables!), for-loops (iterate over your lists!), which seemed to make sense.
This is how I want documentation written for features added to a language.
For example, why were arrow functions added to JavaScript? The documentation should explain the problem and motivation for why it was added to the language with demo code so someone can directly experience the problem.
I want this for every single feature added after the 1.0 release. Not just for JS, but for every language, library, and framework.