Microsoft Manuals...

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.

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

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).

Too real.

Pretty sure every tech person at some point or another has had to do exactly that. And not just their mom, but their dad, and their extended family, and their parent’s friends who have a random problem, etc

I taught basic computer literacy. I am a software developer. It's tough to reframe my own knowledge so drastically, but the new perspective also makes me question why so many things are wrong with current tech (particularly UI/UX).

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 :(

Every front-end guide, despite modern HTML/CSS3/ES6+ being completely viable for building an entire web application without dependencies: "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!"

I swear centering in css is intentionally left as a Lovecraftian mess simply so front end devs can feel superior

Well that's because markdown is for documentation, and we all know programmers don't know how to write documentation.

understands how to write footnotes

x

The footnotes link to the list instead of the actual footnotes. I was quite confused.

You can be pretty technical/capable and still write that article (especially if you have technical expertise outside programming). I have never felt so seen.

I worked my way up from arduino -> RasPi -> Debian -> Self hosting quite a few things. I'm very much a hobbyist/novice, but I'm used to learning. It is so hard to read some documentation and understand what something even does sometimes. This goes double for incredibly useful tools for monitoring/implementing other tools. Like I swear I read the kubernetes descriptions 30x before I realized what in the hell it actually does, and now I'm probably about to break my entire home network with it because I think it's cool as hell.

Also, to your comment specifically: I can get sensors on PCBs I personally made collecting data, throwing it through my own MQTT broker, hosting a dashboard etc, all at a remote site across state lines. I have no idea wtf markdown is. I use yaml for HA stuff with the ESPs, but I don't know why markdown is a thing and it's not just python.

And I am 1000% sure there is a very good reason for 98% of this. But yes I found this article hilarious. In my personal circle of hell all nouns end in "-ly".

as of right now the second xkcd you linked is in an identical format to the newest xkcd. Not relevant to the post, just think it's cool

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.

"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"

Something that's quite interesting is that apparently one of the core components of how Latin and Greek used to be taught in fancy public schools (especially in like, Isaac Newton's era) was that students would be made to copy out sections from classical literature (such as the Odyssey). Obviously this would be happening alongside lessons involving basic grammar, but I've seen some scholars suggest that this kind of blind repetition was a key component to the language learning, and that it may even be useful for learning languages in a modern context.

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 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.

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)

Actually!

I went to the comments expecting some more jokes but found multiple dissertations instead wtf.

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.

RTFM is a form of self help that really should return to the modern zeitgeist

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.

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#