Not to mention this is mostly in unpaid FOSS
Paid documentation writers at Microsoft are absolutely horrible at it too. That's why I can relate to the post so much
SmartmanApps
joined 2 years ago
“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#
RTFM
The problem is the manuals which are written exactly as described in the post
“it’s very easy!”
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.
use developer language
Microsoft uses Microsoft language, and the only people who understand it are people who have been Microsoft programmers for a long time.
sitting in the bubble of experts
Yep, the Microsoft ecosystem is completely unwelcome to newbies. It's by experts for experts, and everyone else can go to hell
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!).
most people writing these things aren’t paid.
I wasn't paid to write Creating MAUI UI's in C#. Didn't stop me from doing a proper job of it.
Apparently so.
Except the manuals are written like this, and don't cover pre-requisite knowledge at all - don't even link to it!
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 writing good documentation
But you can certainly expect them to link to resources about pre-requisite knowledge, like I did in Creating MAUI UI's in C#.