While some may argue there is no such thing, I disagree. And being disagreeable, I’ll get right into this.
I think visually. When I deal in information and processes, I want diagrams. Pictures. Something that lets my primate brain think and perceive in multiple dimensions. If I have to face a wall of text, I am not at my best so far as learning goes.
In the world of software development, the apparent gold standard is the wall of text. As is a dictionary approach to explaining anything.
Way back in the previous century, there was the 80 character by 24 line monitor, probably monochrome green or orange. Inside this visual jailhouse, programmers wrote descriptions and documentation in text alone, in courier font. It was compact, terse stuff. People who did well without any visual aids beside the ASCII alphabet did well. They became the elite. The trend setters. The Alphabetically Correct.
To this day, the legacy persists. You can see it in any coding standard requiring line lengths be limited to 80 characters. Rationale? None other than thats the way it was always done because Grandpa’s monitor could not display any more than that. In 1970. So we better all suck it up and code like its 1970.
And these aging codgers demand all explanation be text, text alone, and nothing but text. Its the gold standard, one followed to this day despite the ability to slam a dozen detailed diagram across the net in less than a second.
A few people persist in doing things the “wrong” way. Take this wikipedia article on AVL trees. There is textual explanation, sample code, and the forbidden – DIAGRAMS. Holy crap, someone might catch on to what an AVL tree is, what it can do for them, and how to futz with one. Probably 20 times faster than with the pure wall of text those elite programming gods of the 1970s would have written and demand to this day.
Diagrams showing how things work to a creatures that evolved with an awesome capacity to think in color, in motion, and in space? How could anyone imagine that would be useful, when there is a perfectly serviceable ASCII character set to explain everything in? Apparently not most of the programming language, library, and framework developer / documenters.
At best, you get some contrived or simplistic examples. And thats fine, though they are too often non-extensible or without a context. This forces you to conduct a series of experiments when something goes wrong.
My current personal favorite is where the original context goes when a click driven event handler in an object invokes a jQuery $.post or $.ajax which returns a Promise and somewhere else in that object, you attached a .done() to it and in that code is … wheres my object context? When this stuff works, it is a beautiful thing. When it does not, its a frikken hair pulling, monitor punching, cuss-spittin’ nightmare.
All the simplistic examples work. But then, every example is only talking through the DOM, not through a series of events in a self-updating object. There is nothing visual to show me where all these inputs (event args, this or $this) end up or become gone. When your experiment means grinding everything down to the properties of passed objects and pumping their names and values and types through console.log, the documentation has failed.
Failed. Yet the jQuery documentation is better than most.
I don’t mind doing some experimentation. It leads to improved understanding, every time. But how much should you need to do? If perhaps a couple of diagrams eliminated 20 hours of frustration where I learned nothing but new ways of stringing together a variety of expletives, I might have found some cool features and uses, and a decent level of comfort with using them.
When I am finally done my explorations, I will make the diagrams that should have been available. These will be added to my own how-it-works documentation, though having gotten that far I probably won’t need to look at them again. What I expect is certain things will be obvious in hindsight, and hindsight alone. For they surely are not in the docs.