> Yes. It's the syntax alongside prose explaining the behavior in detail. Go give it a read.
Bold of you to assume that I or the others didn't. I made my statement in spite of reading it. Not because I didn't read it. So my opinion is unchanged here.
The point here is simple. Documentation is a very important addition. But you can't paper over other deficiencies with documentation, especially if you find yourself referring the same documentation again and again. It's an indication that you're dealing with an abstraction that can't easily be internalized. Throwing the book at everyone isn't a good solution to every problem.
> Have you read the [0] docs for Python's 'subprocess' library? The ...
Yes, I have! All of those. Their difference with bash documentation is that you get the idea in a single glance. I spend much less time wondering how to make sense of it all. Python's abstractions are well thought out, carefully selected, consistently and orthogonally implemented and stays out of the way - something I can hardly say about bash. If that's not enough for you, Python has something that bash lacks - PEPs. The documents that neatly outline the rationale behind their decisions. That's what a lot of programmers want to know and every programmer should know.
Fun fact: The Epstein files contain a copy of the bash manual! Of course they weren't involved in his crimes. It was just one of the documents found on his system. A sysadmin is believed to have downloaded it for reference. But it's telling that it wasn't the Python manual, or the Perl manual, or something else. Meanwhile, I don't really think that Epstein was running Linux on his system.
> Unless you want to underdocument and leave important parts of the behavior for users to incorrectly guess, such documentation is going to be much larger than a cheat sheet would be.
If properly designed, such expansive documentation would be unnecessary, as they would be obvious even with the abstractions. For example when you use a buffer abstraction in modern languages, you have a fairly good idea what it does and why you need it, even though you may not care about its exact implementation details. That's the sort of quality where bash and other POSIX shells fail on several counts. In fact, check how many other shells break POSIX compatibility to solve this problem. Fish and nushell, for example.
"The developer is too lazy to read the documentation" isn't the appropriate stance to assume when so many are expressing their frustration and displeasure at it. At some point, you have to concede that there are genuine problems that cannot be blamed on the developer alone.