I like how some sentences contain phrases that actually make sense:

Despite the jaggle of the chromus, it’s really multi-purpose.

Also me, writing a lot in bash, can totally relate to this:
[[]][[]][[]][[]]][[]()()()()()()()()(){{}{}{}|{}{|}{}{|}{ ////////////////!! !!!! !! //// !!!
Except there should be backslashes, single and double quotes in it too.
Here's a real world example of getting the value of an array member, with a counter:
x="${array[$((i+=2))]}"

kleptomitrons

I want some of those please.

Yes, you are not wrong here.

What I regularly have to deal with is about as bad. Big project, and every upgrade replaces one key element. They have never heard of backwards compatibility. If they don't like a subset in their system, they replace it. Complete with different API calls, structures, and calling conventions. And they may document parts of it three versions later. If at all. Some documentation is basic Doxygen - just list the function parameters, and that's it. I've seen cases where the documentation of the rather critical parameter "flags" was just the word "flags". I've seen cases where the return value was documented only as "status". Not even with a notion whether 0==success and 0!=failure or vice versa.

And no, it is not a closed application. They have an "extension" folder for user-supplied extensions. The problem: If it is not a core extension that has been updated with the main project, the first thing after an upgrade is finding out where your formerly working extension critical to your project now fails, because they just happened to think that the call interface for the boogaloo object need a complete overhaul. Maybe it needed an overhaul, but then at least keep the older interface alive for at least a few versions after documenting the new interface and marking the old one as deprecated.

So basically Swift on macOS, except this made much more sense. 👍

If you don't understand the "problem" part in the "what problem does this tool fix?" Then you probably don't need that tool. You should probably try the program they mentioned that didn't fix their specific problem. Since that program probably has way more users and a more entry-level documentation.

TBF, if your step by steps instructions works, it doesn't matter how complicated the command is.

When it comes to documentation, at least for myself when I'm learning new things, I like to look at it like a recipe book.

The book shouldn't contain just the ingredients and what the final product looks like. It needs to be more in depth than that. It needs to contain the ingredients that go into it, how much of those ingredients, the time to cook, what consistency to look for, prep time, etc.

There are plenty of people out there who have never cooked before, and a recipe book/instructions on how to cook a favorite dish is the perfect way to share your love of the craft and the dish that you made. Then, with your recipe as a guideline, people could change it to suit their tastes, and so on and so on.

That's just how I look at it. I wish I could interpret developer instructions and write up a more user friendly documentation for them. I would love to be able to give back to the community in some more meaningful way than just barely knowing what the developer is providing and using it and making a mess of it my first few tries until I learn from my mistakes.

Boop!

I'm going to steal some of these words and use them in my future projects, and no one can stop me from doing that

If it's all gobbledygook to you, then you weren't the target audience.

Most developers are writing for developers who have approximately the same skill level and knowledge. The vast majority of tutorials out there are definitely not aimed at beginners. They're aimed at peers who know most of the same stuff, but want to broaden their horizons a little.

Now, if it were 95% easy to follow, and then there was one step that was only a few words long and made no sense at all, that would be the typical badly written tutorial. There are way too many tutorials that have a "rest of the owl" problem at some stage. I was trying to figure out how to do something today and I must have skimmed through 30 tutorials aimed at people roughly my skill level before I finally found one that explained the missing bit. That missing bit turned out to be pretty easy, but almost every thing I read just assumed people knew how to do that part, and focused in on all the wrong things.

As for actual tutorials for beginners, the biggest problem isn't that they're badly written. The biggest problem is that they don't exist. But, to be fair, they're actually really hard to write. Explaining things requires that you really understand them well. But, when you understand them well, it can be hard to put yourself in the shoes of someone who knows so little they don't even know what questions to ask. Most computerey things are complicated enough that by the time you feel confident enough to write a tutorial, you've forgotten what it was like to be a beginner.

I feel that way about pretty much anything these days. The sheer volume of options and the complexity of everything is simply exhausting. Even finding food for my cat is overwhelming.