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.
If it’s all gobbledygook to you, then you weren’t the target audience.
Beginner’s 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.
Most developers are writing for developers who have approximately the same skill level and knowledge
If they had the same skill level and knowledge then they wouldn’t need a tutorial to begin with.
The vast majority of tutorials out there are definitely not aimed at beginners
And that’s precisely the problem with the vast majority of tutorials.
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
Microsoft: Now all you have to do is add in a GDG
I must have skimmed through 30 tutorials aimed at people roughly my skill level before I finally found one that explained the missing bit
Now imagine reading Mircosoft documentation and not being able to find anything which explains what GDG is. Classic “rest of Owl”.
they’re actually really hard to write
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#
Most developers are writing for developers who have approximately the same skill level and knowledge
I think you’re correct about this, but I also think that’s part of the problem.
On the one hand you can have technical tutorials for technical people, but to your point assuming the audience has the same skill level and knowledge is actually a mistake - no two people share the same same life, so while it’s reasonable to assume a certain level of knowledge, you still need to consider that there may be gaps - small gaps but gaps all the same and that it’s worth being explicit about things to avoid ambiguity. A common pitfall I see in a lot of tutorials or guides is not being explicit about file paths (“just add this to the config folder” - which folder? Where?), or not correctly steering the user towards the relevant documentation about configuration values while still expecting them to insert some config file specific to their system, stuff like that.
The other end of the spectrum - the beginner, to your point might not be the target audience but a lot of people don’t realise that those folks exist. The absolute classic example I see of this is Linux for the Everyman - Lemmy is very big on promoting Linux and moving folks away from Windows/MacOS but there’s a bit of a disconnect because a lot of tutorials exist that base level of knowledge that a complete beginner doesn’t have. So they’re both not the target audience but expected to learn that stuff - and of course it doesn’t work and they stick to what they do know.
All this is to say, writing tutorials is a skill in itself and part of that skill is knowing who your target audience really is and knowing where your knowledge is his experience from working at something for so long or a basic level of understanding you expect a user to have.
“just add this to the config folder” - which folder? Where?
This is one of the biggest problems with Microsoft documentation (and maybe other ecosystems too). Doesn’t include any “using” statements in the snippet, leading to copying the code not working, because you don’t know what DLL this is using. They talk about 2 lines, and show you 2 lines, but the 2 lines don’t work without 1 or 2 other lines which they have left out. Happens every single time
not correctly steering the user towards the relevant documentation about configuration values
Microsoft documentation never links to anything else at all. If you don’t know how to do this thing they’re talking about, well now you have to go find a Youtube by some Indian programmer about it
there’s a bit of a disconnect because a lot of tutorials exist that base level of knowledge that a complete beginner doesn’t have
Yep. The man pages are so not user-friendly. I have always said that Unix is very powerful, but not the least bit user-friendly. Welcome to low adoption.
