The issue here is that the author of that post, and potentially the fictional author of the thing being lampooned, are not drawing a distinction between a tutorial (or an explanation) and a how-to.

https://diataxis.fr/

Either you want to get a task done, or you want to spend a lot longer learning how to work that out for yourself.

(Many tutorials will include small set of how-to-like instructions because emulating the actions of a master will improve one’s vocabulary of what can be done as well as how it is achieved.)

The more advanced the level of knowledge on something the more foundation knowledge somebody has to have to even begin to understand things at that level.

It would be pretty insane to in a tutorial for something at a higher level of expertise, include all the foundational knowledge to get to that level of expertise so that an absolute beginner can understand what’s going on.

Imagine if you were trying to explain something Mathematical that required using Integrals and you started by “There this symbol, ‘1’ which represents a single item, and if you bring another single item, this is calling addition - for which we use the symbol ‘+’ and the count of entities when you have one single entity and ‘added’ another single entity is represented by the symbol ‘2’. There is also the concept of equality, which means two matematical things represent the same and for which the symbol we use is ‘=’ - writting this with Mathematical symbols, ‘1 + 1 = 2’” and built the explanation up from there all the way to Integrals before you could even start to explain what you wanted to explain in the first place.

That said, people can put it in “recipe” format - a set of steps to be blindly followed without understanding - but even there you have some minimal foundational knowlegde required - consider a cooking recipe: have you ever seen any that explains how does one weight ingredients or what is “boiling” or “baking”?

So even IT “recipes” especially designed so that those with a much lower level of expertise than the one required to actually understand what’s going on have some foundational knowledge required to actually execute the steps of the recipe.

Last but not least I get the impression that most people who go to the trouble of writting about how to do something prefere to do explanations rather than recipes, because there’s some enjoyment in teaching about something to others, which you get when you explain it but seldom from merely providing a list of steps for others to blindly follow without understanding.

So, if one wants to do something way above the level of expertise one has, look for “recipe” style things rather than explanations - the foundational expertise required to execute recipes is way lower than the one required to undertand explanations - and expect that there are fewer recipes out there than explanations. Further, if you don’t understand what’s in a recipe then your expertise is below even the base level of that recipe (for example, if somebody writes “enter so and so in the command prompt” and you have no fucking clue what a “command prompt” is, you don’t meet the base requirements to even blindly follow the recipe), so either seek recipes with an even lower base level or try and learn those base elements.

Further, don’t even try and understand the recipe if your expertise level is well below what you’re trying to achieve: sorry but you’re not going to get IT’s “Integrals” stuff if your expertise is at the level of understanding “multiplication”.

Yeah, documentation isn’t as good as it could be, and it would increase the accessibility of software if it was better.

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

I think people (I foremost) should train the skills to skip tutorials/articles that are %80 not understandable (to the particular reader in question, not generally) rather than obsessing over them.

How I, a developer read most developer blogs too. No shame in admitting that I lack knowledge, except my anxiety don’t cut me such slack.

How about that worst of both worlds, the tutorial where the author starts out writing as if their audience only barely knows what a computer is, gets fed up partway through, and vomits out the rest in a more obtuse and less complete form than they would’ve otherwise?

1. Turn on your computer. Make sure you turn on the “PC” (the big box part) as well as the “monitor” (TV-like part).

2. Once your computer is ready and you can see the desktop, open your web browser. This might be called “Chrome”, “Safari”, “Edge”, or something else. It’s the same program you open to use “the Google”.

3. In the little bar near the top of the window where you can write things, type “https://www.someboguswebsite.corn/download/getbogus.html” and press the Enter key.

4. Download the software and unarchive it to a new directory in your borklaving software with the appropriate naming convention.

5. Edit the init file to match your frooping setup.

6. If you’re using Fnerp then you might need to switch off autoglomping. Other suites need other settings.

7. Use the thing. You know, the thing that makes the stuff work right. Whatever.

Congratulations! You’re ready to go!

This reminds me of the “WHY IS THERE CODE??? MAKE A FUCKING .EXE FILE AND GIVE IT TO ME” post that blew up a while back

https://copypastatext.com/i-am-new-to-github-and-i-have-lots-to-say/

And both boil down to

• guides can be prioritized more in some projects and it might be in the best interest of the creators to do that

• different guides are written for different audiences, sometimes a guide isn’t meant for the average person

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.

I fucking HATE it when the fisterfunk will not talk to the shamrock portal or even send beep-boops back to the Snarfus!

Imagine a chemistry lab tutorial aimed at 9th grade students getting “as a non-chemist, this reads as gibberish” comments from first graders. Nobody would blame the tutorial authors.

People need to start putting in the effort. There is no such thing as learning for free.

At least once in their life, every tech person should be forced to teach someone like my mum how to use a piece of technology.

That will very quickly change your perspective on what counts as user friendly.

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.

Is “prerequisite knowledge” a foreign concept to people these days? When I started writing extensions for Blender, I had to do a lot of legwork to understand the bpy module, and even more fucking legwork to understand Python itself, all that on top of the general knowledge of programming and algorithms from high school.

RTFM means that you should use the available resources to learn. There’s a whole internet full of them. There are no shortcuts to understanding, and you can’t expect every task-oriented guide to explain how to write a main().

I really enjoy this writing style. It reminds me of what it was like reading Dave Barry’s Sort Of History of the United States when I was a kid.