“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!
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.
RTFM is a form of self help that really should return to the modern zeitgeist
The problem is the manuals which are written exactly as described in the post
For people to RTFM, you need clear and concise manuals for different groups of users.
It’s no use addressing most IT-related manuals without prerequisite knowledge and practical experience.
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.
Microsoft uses Microsoft language, and the only people who understand it are people who have been Microsoft programmers for a long time.
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.
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”.
Yep, the people who write the Microsoft documentation assume that the readers know everything they already know.
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 😂
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#