People say “RTFM” then you get to the manual and it’s this
Microsoft Manuals…
That is spot on. Usually you would expect the manual to be hit and miss when it comes to troubleshooting but Microsoft is consistently miss, skipping the important parts and details.
Microsofts documentation is also increasingly just outright wrong:
if you spend enough time looking up things about their newer products like M365, defender, or azure, especially when it comes to scripting related to those, there’s a ton of simply outdated info on the official docs that makes it really difficult to figure out why your setup isn’t doing what it’s supposed to.
from changed variable names, to missing functions, to unexplained buttons, etc., etc.
the newer docs are straight up trash!
you’re better off searching around for forum posts or whatever, than using the official docs…
Microsofts documentation is also increasingly just outright _wrong_:
There used to be a spot on joke about Microsoft documentation taking the piss out of the fact that it was always 100% accurate but at the same time pretty useless. That joke hasn’t been relevant for a while.
It’s so frustrating trying to find out how to do something in one of the admin centres for M365 and you find a Microsoft document with exactly what you need in it only to find out that the UI has changed and the steps don’t work now. Did they move it? Did they remove it? Who knows?
our admins are regularly straight up fighting against this bs!
“where the fuck has this fucked off to now?? it was right here last month?!”
so glad I’m not doing MS administration…
If you are used to documentation like MS’s, then AI responses probably look more reasonable and useful. If AI results look better than your own docs you should feel really bad.
this is the part that’s really frustrating:
i sometimes feel forced to use chatGPT (duck.ai) to simply search for Microsoft things, because search engines only return SEO garbage with the exact same content spammed across like a million “tech tips for beginners” sites…and the docs, as established, are pretty useless…
keep in mind: i fucking hats “AI”.
making me use it makes me not have anything to do with whatever you’re selling.
it’s getting progressively more impossible to simply use MS products, because the information you need to use them is so hidden away!
combine those two things and ta-da: that’s why all my stuff at home is running linux now.
Amazon is no better. Go look up the correct parameter format required to set a compliance lock on an object in S3 via the API. Now try it yourself. Surprise!
you’re better off searching around for forum posts or whatever, than using the official docs
Yep, that’s why I started the Lemmy .NET MAUI Community - try and reassemble the collective experts who got scattered when Microsoft shutdown the old Xamarin forum - they had been invaluable when I was trying to learn Xamarin from the Microsoft resources.
oh hey, that’s great! thank you!
Also, requiring login.
Basically Hello World using the win32 API. I believe I first encountered this before college, and it took actually professional dev experience to really understand it.
Another problem is that people skim to the “most important bits” without knowing they’re skipping something important. Then some of those people complain how the manual is shit.
I guess it could be shit if it is way too verbose though.
Exactly what I was thinking. Like needing to understand a huge preamble just to do the Very Simple Thing. I just want to move on, not marry this Linux command.
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?
-
Turn on your computer. Make sure you turn on the “PC” (the big box part) as well as the “monitor” (TV-like part).
-
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”.
-
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.
-
Download the software and unarchive it to a new directory in your borklaving software with the appropriate naming convention.
-
Edit the init file to match your frooping setup.
-
If you’re using Fnerp then you might need to switch off autoglomping. Other suites need other settings.
-
Use the thing. You know, the thing that makes the stuff work right. Whatever.
Congratulations! You’re ready to go!
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).
I think TLA means “Three Letter Acronym” in some circles. So like, DBA would be a TLA meaning “database administrator” for example. Didn’t read the article to get the context though, so not sure if it fits
Yes, TLA is a three letter acronym. A four letter acronym, on the other hand, is an ETLA, or “Enhanced Three Letter Acronym”. For advanced cases, you can get an EETLA (or XETLA) for Expanded/Extended Enhanced Three Letter Acronym.
Just so you know.
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.
-
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.
I think the issue is that you need to understand who your users actually are. Documentation for a library intended to be used by a reasonably competent software engineer is going to have different requirements vs documentation for a cli utility aimed at Arch btw Linux users vs documentation for a program to help Grandma organize family photos.
If you throw a terminal command at Grandma she’s going to panic and call her grandchild. If you put instructions for extracting a tarball in your library docs the programmer is going to get bored and skip ahead.
I just want a friendly user :(
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
-
I envy some people’s ability to come up with nonsense words.
Galabrup, anyone?
I prefer Fizkada more.
Sternocleidomastoid, oh wait, that’s a word. Dang it.
This is a much harder game for Germans.
Ponblopdring!
Like the Turbo Encabulator
You might enjoy !vxjunkies@lemmy.ca~
I love the shit out of this. I can relate SO HARD to everything she wrote. It’s like most people don’t understand how to communicate with regular normal human beings
They have even forgotten one of the most basic grammar rules - always fully spell out an acronym the first time you use it. Looking at you MicroSoft (MS). No, I don’t know what TLA* is, and now this document is completely useless to anyone who doesn’t know what TLA is, especially since you’ve also not linked to any resources about TLA
- Three Letter Acronym
Is… is it not standard to say “Three Letter Acronym (TLA)” the first time? What kind of monster?
What kind of monster?
MS 😂 🤬
As a software developer with 10+ years in .Net.
I was forced to try and use it as a brand new to Microsoft (not just .NET, all of Microsoft) programmer (my experience was in other ecosystems). Not recommended.
As a software developer with 10+ years in .Net. I don’t even bother with Microsoft documentation anymore, it’s often wrong or outdated and skips chunks that even senior devs need.
My God y’all can’t just let a joke be a joke if there’s an option for you to be correct instead, LMAO
Edit: I just scrolled through all the comments and saw that the large majority of the replies here are very long, multi-paragraph comments. Y’all ok? Did this post touch a nerve with some of you? LMFAO
Actually!
I went to the comments expecting some more jokes but found multiple dissertations instead wtf.
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”.
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.
For “all documentation” to “cater to all levels” it would have to explain to people “how do you use a keyboard” and everything from there upwards, because there are people at that level hence it’s part of “all levels”.
I mean the your own example of good documentation starts with an intro of “goals” saying:
“Visual Studio (VS) does not (currently) provide a blank .NET Multi-platform Application User Interface (MAUI) template which is in C# only. In this post we shall cover how to modify your new MAUI solution to get rid of the XAML, as well as cover how to do in C# code the things which are currently done in XAML (such as binding). We shall also briefly touch on some of the advantages of doing this.”
For 99% of people almost all that is about as understandable as Greek (expect for Greek people, for whom it’s about as understandable as Chinese).
I mean, how many people out there in the whole World (non-IT people as illustrated in the actual article linked by the OP) do you think know what the hell is “Visual Studio”, “.Net”, “Multi-platform Application User Interface”, “template”, “C#”, “XAML”, “binding” (in this context).
I mean, if IT knowledge was a scale of 1 to 10 with 10 the greatest, you’re basically thinking it’s “catering to all levels” when an explanation for something that is level 8 knowledge (advanced programming) has a baseline required level of 7 (programming). I mean, throw this at somebody that “knows how to use Excel” which is maybe level 4 and they’ll be totally lost, much less somebody who only knows how to check their e-mail using a browser without even properly understanding the concept of "browser (like my father) which is maybe level 2 (he can actually use a mouse and keyboard, otherwise I would’ve said level 1).
I think you’re so way beyond the average person in your expertise in this domain that you don’t even begin to suspect just how little of our domain the average person knows compared to an mere programmer.
it would have to explain to people “how do you use a keyboard”
No it wouldn’t. You just link to resources about pre-requisite knowledge.
and everything from there upwards
Nope. Exact same thing applies to all pre-requisite knowledge.
For 99% of people almost all that is about as understandable as Greek
Now scroll down to the pre-requisite knowledge which has links to things explaining ALL of that.
how many people out there in the whole World (non-IT people as illustrated in the actual article linked by the OP) do you think know what the hell is “Visual Studio”, “.Net”, “Multi-platform Application User Interface”, “template”, “C#”, “XAML”, “binding” (in this context)
Exact same number as there is people capable of clicking on the provided links about them.
which is maybe level 4 and they’ll be totally lost,
…until they read the links in the pre-requisite knowledge, and then they will understand all of it.
I think you’re so way beyond the average person in your expertise in this domain
says person who didn’t even scroll past the introductory paragraph! 😂 You think people try to learn things by reading only the introductory paragraph?? 😂
you don’t even begin to suspect just how little of our domain the average person knows compared to an mere programmer
And yet, weirdly, if you keep reading you’ll find it caters to people who know nothing about it 😂
I Prefer a playbook to a recipe card. The playbook should spell out the goal and the 'why’s of the steps. Because if the process throws an error due to upgraded code etc, then you can be stuck at step one with no path forward. With some playbook annotation you at least know expected out come and why you are running a command etc.
When I have gone to docker hub I always view multiple images and see what their writeup is like. Some just assume you 100% know all dockers subtleties, some have a one liner, but there will be a helpfull soul who spells out what steps to do, and what the best options to set etc. Like a mini tutorial.
I find the mini tutorial to be widely beneficial, because it removes the blackbox nature, and gives new onboarding users a chance to grasp the concepts docker works with.
It’s like the difference between going to a mechanic that has you sit by the coffee machine in the office while they change your brakes and they come back and say “I swapped the new pads in”, vs them pulling up a chair in the shop and explaining the process “here I’m wirebrushing the back of the wheel and the hub, to make sure when it goes back on there is no corrosion debris stopping a parallel fit…now I’m applying high temp grease so that the hub and wheel don’t sieze together from corrosion and make next removal easy”
The info is probably useless to a seasoned mechanic that had a broken hand so had somebody else do their brake work, but highly useful to the next gen of person that can absorb it and know whats and whys.
It’s like the difference between going to a mechanic that has you sit by the coffee machine in the office …
Good example. I just wanted to add that the place I go to for tyres, if there’s some kind of issue (like with balance or alignment), sometimes they even take me into the workshop (where customers are usually not allowed) to show me what the issue is.
Yeah, that’s much better.
Personally I detest not understanding what’s going on when following a guide to do something, so I really dislike recipe style.
That said, I mentioned recipes because recipes meant to be blindly followed are the style of guide which has the lowest possible “required expertise level” of all.
I supposed a playbook properly done (i.e. a dumbed down set by step “do this” guide but with side annotations which are clearly optional reading, explaining what’s going on for those who have the higher expertise levels needed to understand them) can have as low a “required expertise level” as just a plain recipe whilst being a much nicer option because people who know a bit more can get more from it that they could from just a dumbed down recipe.
That said, it has to be structured so that it’s really clear that those “explanation bits” are optional reading for the curious which have the knowhow to understand them, otherwise it risks scaring less skilled people who would actually be able to successfully do the taks by blindly following the step-by-step recipe part of it.
That said, it has to be structured so that it’s really clear that those “explanation bits” are optional reading for the curious which have the knowhow to understand them
Yep, totally. This past year I spent a lot of time setting up an LMS with content.
I included sections that were tips, good to know, for awareness, etc.Maybe only 1 out of every 20 users might expand the section, but if they do then there is a clear explanation of why this particular thing functions this way and how to make it work in alternate usecases. Images and explanation, before and after, etc.
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.
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.)
I like her “written by a human” badge. Never saw one before. Gotta say I was wondering, which probably lends to her point.
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
bpymodule, 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 mean, as it says at the end, this blog post is in good fun. It most definitely expresses frustration, but it also recognizes that perfect is the enemy of good, and that you already put in more effort than one can expect by writing a tutorial to begin with.
I guess, my main takeaway is that you really don’t need to bother writing up your life story. It will fly over the head of your readers, for sure. (Although a bit of context may still be important.)
And you should probably spend a few more words, describing the actual steps, no matter how obvious those may seem to you.that you already put in more effort than one can expect by writing a tutorial to begin with
Nope. If a job is worth doing, it’s worth doing well.
There’s amazing and terrible manuals everywhere. One of the key things is defining target audience. From there you define experience and knowledge.
If a manual is intended to be for a broad audience interacting with something new, then you use the lowest level reading level that still makes your point. From there you work on flow because there’s a 1000 ways to skin a cat.
If LEGO manuals were only written step by step instructions, at a college reading level, then they miss a key demographic. Yet, people would still walk around like “That’s a perfectly cromulent instruction manual!” Technically they would be correct but it misses the point.
There’s amazing
IBM
and terrible manuals everywhere.
Microsoft
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#.
Reminds me of one of my favourite Xkcd.
Although I guess we are more in this one, really.I’m really impressed by people who can write stuff that makes kinda sense, while being complete gibberish. Very funny and y’all need to remember where you are.
Yeah, documentation isn’t as good as it could be, and it would increase the accessibility of software if it was better.
The amount of time and skill it takes to write excellent and accessible documentation is just not reasonable for most developers, unless you have dedicated technical writers or it’s a personal project without true deadlines.
So what? It may arguably be not a developer’s fault, but it is everyone’s problem, given the growing dystopian alternatives to an accessible distributed software ecosystem. A problem can be acknowledged without admitting blame. Happy cake day btw.
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.
If it’s an instruction to a dishwasher liquid, you better write it for first-graders.
Sure, if you write a documentation to some developer tools, use developer language.
But if it’s something you expect regular folk to use, think of how much more people could use it if they wouldn’t need to learn something entirely out of their field of expertise to use it.
You can make dishwashing liquid kit that would require extensive knowledge in organic chemistry to use. It would be cheap and darn simple to develop. You could release it today! You just…shouldn’t.
Remember people have their lives, and shouldn’t be forced to comprehend everything around them at a professional level. Many developers seem to forget about it A LOT somehow, shifting it to the user and saying “I’m done here”, sitting in the bubble of experts and treating users like stupid rats who can’t simply get a computer science degree to use their computer. As a food technologist, I recently developed a premix for home-baking of phenylalanine-free pastry, and 70% of the work was making it idiot-proof. It is true for any field, yet it is important. People can’t learn everything every time they need something, and it’s not their fault.
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
I haven’t read the article but from the title and header alone, it already reminded me my experience of hosting Lemmy with 0 experience with self hosting. I learned how to start a docker and host a very basic stuff according to docker tutorial, no issue, but as i venture into hosting Lemmy where people keep saying “it’s very easy!”, i keep failing to do so because the tutorial itself written with a lot of jargon and also missing step (i remember running into a part where the tutorial asked me to just fill in necessary stuff. Which necessary stuff???), i eventually given up. Not sure if they rewrite it recently but i can’t be bother with these anymore.
The point here i assume is sometime dev with tons of experience expect people to know what they know, and then written stuff in heavy jargon for the basic tutorial. It’s a curse of knowledge.
“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.
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#
You sure that’s a tutorial and not the “about” page of half of github, where you have no fucking clue what the project is about?
