“first, install npm and npx and npy and npppp2 and then run ‘npz create-huge-boilerplate-folder’. Now go edit arbitrarily_named_file.yaml to add requirements a, b, and banana. Now you can edit path/to/hidden/entrypoint.jsx to return ‘Hello, World!’ and then run ‘npz bloated-dev-http-server’ and navigate to http://127.0.0.1:9001/index to view it! Simple!”
Is “prerequisite knowledge” a foreign concept to people these days?
Apparently so.
RTFM means that you should use the available resources to learn
Except the manuals are written like this, and don't cover pre-requisite knowledge at all - don't even link to it!
There’s a whole internet full of them
Microsoft doco "now add TLA to it", don't say what TLA is, don't link to what TLA is, searching for TLA doesn't tell you what it is. There most certainly is a whole internet full of blogs about "TLA", but I don't even have any keywords, and can't find any of the "TLA" that Microsoft is talking about. The documentation is literally useless to anyone who doesn't already know what "TLA" is.
There are no shortcuts to understanding
There are no shortcuts to writing good documentation
you can’t expect every task-oriented guide to explain how to write a main().
But you can certainly expect them to link to resources about pre-requisite knowledge, like I did in Creating MAUI UI's in C#.
“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.
If it’s all gobbledygook to you, then you weren’t the target audience.
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.
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#
A lot of experienced people say that, and it isn't to a beginner. The infamous example in Maths circles is "the proof is left as an exercise for the reader". In other words, "I couldn't be bothered writing this because I'm assuming you already know how to do it".
It’s a curse of knowledge
Yep, the people who write the Microsoft documentation assume that the readers know everything they already know.
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
I tutor Maths. I have a Year 12 student who has forgotten things they were taught in Year 8, and the teacher has done no revision of it in class. Now guess why this student needs a tutor 😂
People need to start putting in the effort.
The people writing the documentation, yes. They need to say what the prerequisite knowledge is, and include links to it for those who don't know it (or remember it). Only takes a few minutes to do that. See Creating MAUI UI's in C#
I think TLA means “Three Letter Acronym” in some circles
Yes, that was why I used it. Microsoft doco is full of unexplained TLA's - you have to already know what it means and how to use the thing. You knew what TLA meant. Now read the Miscrosoft doco where you don't know what any of the MS TLA's mean, and they don't tell you.
I’ve seen cases where the documentation of the rather critical parameter “flags” was just the word “flags”.
In Microsoft documentation it would just say "FLGs", with no explanation of what FLG is, nor any links to resources about FLGs. you either already know what it is or you now can't continue any further with the documentation (because a search for FLG also fails to find what it is). Throughout their documentation it is heavily assumed you are a long-time Microsoft programmer and already know all of this. i.e. it is completely unwelcoming to Microsoft beginners (and even some who aren't beginners)
They seem to exist solely as a reminder to those who already know
Perfect description of the entire Microsoft .NET documentation, signed, .NET beginner who not only didn't have a .NET background, but not even a Microsoft programming background (which is also heavily assumed throughout - way to make newbies feel completely unwelcome in your ecosystem!).
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
You don't need to include it all. You just need to mention it as pre-requisite knowledge, and link to resources about it for those who don't have that knowledge. See Creating MAUI UI's in C#
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
Good documentation includes both. i.e. step-by-step guide, with explanations. See above.
so either seek recipes with an even lower base level
All documentation should cater to all levels. See above.
Instead of writing that snarky comment you could’ve instead used the web for its original purpose and conduct your own research and not bug strangers on the internet to do your bidding
You're not the only one they're doing it to (I went to their profile to see if this is a pattern, and it sure is).
Sounds like typical Microsoft documentation to me. Explains in great detail what .NET is, where you can download it from, then jumps straight to the advanced topic they're covering without any of the intermediate knowledge covered or even linked to (but perhaps referred to only vaguely in passing as an acronym, again with no link, this time no link to what "TLA" is actually short for, so you're searching for it is fruitless as well).
Yep, Microsoft doco is like that too