“Hello! I am a developer. Here is my relevant experience: I code in Hoobijag and sometimes jabbernocks and of course ABCDE++++ (but never ABCDE+/^+ are you kidding? ha!) and I like working with Shoobababoo and occasionally kleptomitrons. I’ve gotten to work for Company1 doing Shoobaboo-ing code things and that’s what led me to the Snarfus. So, let’s dive in!
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.
Beginners are the target audience for tutorials. Many tutorials are written in gobbledygook. See Microsoft documentation, which would’ve instead said GDG, and assumed you knew what GDG was.
If they had the same skill level and knowledge then they wouldn’t need a tutorial to begin with.
And that’s precisely the problem with the vast majority of tutorials.
Microsoft: Now all you have to do is add in a GDG
Now imagine reading Mircosoft documentation and not being able to find anything which explains what GDG is. Classic “rest of Owl”.
No they’re not. You include what the pre-requisite knowlege is, along with links to resources about the pre-requisite knowledge. See Creating MAUI UI’s in C#
No, most of the time they’re not. And you don’t need to warn me that an “s” is coming.
Note that I said “approximately”, not the identical level of skill and knowledge. It’s written by a fooblorts developer who uses migwed and ghai and is now looking to connect suwdo with ugfest. If you’re also a fooblorts developer who wants to connect suwdo with ugfest but you have no experience with that particular thing, then the tutorial is for you. It’s not for someone who has never used any of those technologies and doesn’t understand anything about them.
Ah, I can see you never write tutorials, nevermind then. You have no idea what you’re talking about.