How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner

Controversial, but: Skill issue.

I do a lot of FOSS work. I dont write docs for everyone most of the timr. I write docs for those already educated on most of the items. This still applies, and is accessible to anyone:

If you don't know the word, look it up in the dictionary.

I don't want to downplay frustrations, I know those are real, but most people writing these things aren't paid.

Note: If a Dev complains their idea isn't adopted and the docs suck, that's another story.

Edit: And the article seems to be by a career writer, so it makes sense from their perspective, but some more expansive thinking on their part about how a developer isn't staffed to do their job, too, would be helpful.

On the flipside I've encountered docs that expect the reader to already understand the functionality in order to be able to use the docs. They seem to exist solely as a reminder to those who already know.
There's a reason I don't bother running my own mailservers anymore!
- 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!).
- Oh man, this I do hate. If you have terminology in your app, that is not a standard, please, please define it.
Docs aren't for everybody sometimes stuff is just complex and requires prior understanding. I guess that's where more people can help FOSS projects, by writing more accessible docs and pre packaging stuff so it can be used by less technical people or someone who's just starting out.
- Agreed, maybe this writer could step in and volunteer their time instead of writing satire complaining about it.
How many dictionary lookups deep are people reasonably expected to go? Depending on the reader, there's just some level of complexity that isn't accessible any more. Add to that the diversity of mental models and approaches people take and a semantic structure intuitive to you just won't work for someone else, no matter what words you use. Don't get me wrong, you can't cater to everyone and I'm not sure you should if you could.
I understand that your target audience are typically people already familiar with or at least invested in the subject matter, in which case leaning on a presumed funamental understanding and a willingness to fill gaps is sensible. You don't want to bloat your docs by repeating things your most relevant readers already know.
In doing so, you "sacrifice" the accessibility for less versed people. In a perfect world, we wouldn't have to choose and everyone would get an explanation suitable to their own level of understanding and background. Alas, our world imposes limits on our knowledge, abilities, time and energy. Readers and writers alike should be aware of those limits, both in themselves and in each other.
I feel like "Skill issue" understates the complexity of the combinatorics the diversity of human minds produces. It's a human issue that might never be perfectly solvable. Your solution is good and appropriate, and that has to be enough.
My point is merely that we should be aware of the downsides of our choices and make that tradeoff consciously.
- I think you're spot on, and this is the reason I put "controversial" in front of it. I just felt like if we rewrote the blog post as a "What a writer who's never learned to program's code looks like to a developer" it would make no sense, so why should we accept it in it's current form?
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.
- I'm sorry to tell you, friend, that your article does this too. You don't explain what XAML is, for instance. Certain sentences almost read like the satire you posted: "how to do in C# code the things which are currently done in XAML (such as binding)". You also tell the reader to "edit the relevant line" which doesn't help a total beginner.
  The fact of the matter is that writing for the lowest common denominator takes an incredible amount of time and writing skill. Most of us don't have one, some don't have both.
  If you keep practicing technical writing, I'm sure you'll get there eventually. Just keep in mind that most people do not want to be technical writers
- Others are debating the point about the doc itself, so I won't go there, but just because you enjoyed doing it, doesn't mean others do, or have the time.
  I happen to write really detailed documentation, because I like to, I like the formality of it. However, as I stated in my other comment my complaint is about the assumptions made in the blog post. Specifically:
  I just felt like if we rewrote the blog post as a “What a writer who’s never learned to program’s code looks like to a developer” it would make no sense, so why should we accept it in it’s current form?

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.
- Yooo, seriousely whats going on?? Hahaha

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.

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

As a developer, that is also how I read tutorials written by other developers.

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?

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

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

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.

https://diataxis.fr/

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

Yeah, documentation isn't as good as it could be, and it would increase the accessibility of software if it was better.

How I, a developer read most developer blogs too. No shame in admitting that I lack knowledge, except my anxiety don't cut me such slack.

I like how some sentences contain phrases that actually make sense:

Despite the jaggle of the chromus, it’s really multi-purpose.

Also me, writing a lot in bash, can totally relate to this:
[[]][[]][[]][[]]][[]()()()()()()()()(){{}{}{}|{}{|}{}{|}{ ////////////////!! !!!! !! //// !!!
Except there should be backslashes, single and double quotes in it too.
Here's a real world example of getting the value of an array member, with a counter:
x="${array[$((i+=2))]}"

kleptomitrons

I want some of those please.

Haha yeah, made me think of escape sequences
- Those would not typically be part of a software tutorial, also they are not part of the shell's language.

When it comes to documentation, at least for myself when I'm learning new things, I like to look at it like a recipe book.

The book shouldn't contain just the ingredients and what the final product looks like. It needs to be more in depth than that. It needs to contain the ingredients that go into it, how much of those ingredients, the time to cook, what consistency to look for, prep time, etc.

There are plenty of people out there who have never cooked before, and a recipe book/instructions on how to cook a favorite dish is the perfect way to share your love of the craft and the dish that you made. Then, with your recipe as a guideline, people could change it to suit their tastes, and so on and so on.

That's just how I look at it. I wish I could interpret developer instructions and write up a more user friendly documentation for them. I would love to be able to give back to the community in some more meaningful way than just barely knowing what the developer is providing and using it and making a mess of it my first few tries until I learn from my mistakes.

These days I pretty much just give the code to the LLM and it spits out documentation
Is it prefect? No. But it takes me literally 10 minutes and it's 90% there
In being slightly facetious here, I do spend some time on it to make it appropriate. But it sure does a good job imo
- This is one of those things where I'm actually okay with AI use. I understand a lot of the FOSS community devs don't have a lot of time for such matters, so if this gets it at the very least 90% there, I would consider it a win! (human review being a big bonus, of course!) :-]
I structure my tutorial docs (I write a lot of them for work) like the O’Reilly cookbook series for this reason.
The problem you’re trying to solve is at the top. Next comes a list of prerequisites for the instructions. Then clear, step-by-step instructions with no more than one command or action for each one, highlighting anything that’s different depending on environment.
Then at the bottom I’ll sometimes add a discussion of why each command does what it does, and finally a list of resources for whatever programs or systems the instructions are about.
- Thank you for that. I'm sure the people who read it and got a grasp of what they are trying to accomplish greatly appreciate your going out of the way like that. :-]

Boop!

Oh do grow up, frankly.

When I taught myself to program, there was no internet. You went and bought an enormous, 800 page book (usually written by Charles Petzold) and you hoped to Darwin something, anything would be understandable and lead you to move forward just a little bit.

If it’s worthwhile doing it’s hard.

You recognize the feelings of the author and relate to them personally with Charles Petzold's writing from back when, and say they need to grow up?
I think it's a little reductive to say the author just wants everything to be easy.
- Help me understand what the author is trying to say, please. It could be I’m missing something. It just reads to me like the author feels everybody else has a responsibility to somehow make complicated topics easy.
usually written by Charles Petzold
Classic example of someone who wrote tutorials like the type being satirised.
If it’s worthwhile doing it’s hard
Writing good tutorials isn't hard. You just have to not assume background knowledge of anything you're writing about. If you write it for beginners, then literally anyone can follow it.
- So maybe the tutorial the satirist was satirising just wasn’t quite aimed at the satirist.

TBF, if your step by steps instructions works, it doesn't matter how complicated the command is.

I'm going to steal some of these words and use them in my future projects, and no one can stop me from doing that

I feel that way about pretty much anything these days. The sheer volume of options and the complexity of everything is simply exhausting. Even finding food for my cat is overwhelming.

And that’s what led me to argyling the pintafore with the quagmire instead of the hoobastank!

Tank vs. quagmire, who wins?

I think people (I foremost) should train the skills to skip tutorials/articles that are %80 not understandable (to the particular reader in question, not generally) rather than obsessing over them.

People say "RTFM" then you get to the manual and it's this

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.
Microsoft Manuals...
- 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.
- Link 1: Pencil selection guide Link 2: Ovals vs. circles Link 3: Wings Link 4: Bird feet
- 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.

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

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 :(
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
- Sometimes it's not user friendly, other times it's not friendly users.
- And why? Because none of them can read the fucking manual! And you'll say they don't try, but many of them have tried. Once. And all they learned was that it wouldn't do them any good.
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).
- Oh definitely, there's so many products we use that are far more complicated than they have any need to be.
  Vehicles and appliances are two examples that come to mind.

I envy some people's ability to come up with nonsense words.

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

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

Me, a (mostly) backend developer, reading a Medium post on how to make your computer display a div using Awesome New Web Framework (TM)

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 hear that. I was refactoring a codebase and they used a special library for tooltips. There are two tool tips on the entire site and the library uses its own perverse syntax.
  I've never got into modern JS frameworks because they seem to be utterly insane. If you need all that to build a site, you need to work on your fundamentals.
- “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!”
  Yep, Microsoft doco is like that too
I swear centering in css is intentionally left as a Lovecraftian mess simply so front end devs can feel superior

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 bpy module, 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().

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

I like her "written by a human" badge. Never saw one before. Gotta say I was wondering, which probably lends to her point.

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.

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#
RTFM is a form of self help that really should return to the modern zeitgeist
- RTFM
  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.
- 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.

I fucking HATE it when the fisterfunk will not talk to the shamrock portal or even send beep-boops back to the Snarfus!

asdg a=-do —cd go cd stay —sususudododo baby shark

So basically Swift on macOS, except this made much more sense. 👍

Yes, you are not wrong here.

What I regularly have to deal with is about as bad. Big project, and every upgrade replaces one key element. They have never heard of backwards compatibility. If they don't like a subset in their system, they replace it. Complete with different API calls, structures, and calling conventions. And they may document parts of it three versions later. If at all. Some documentation is basic Doxygen - just list the function parameters, and that's it. I've seen cases where the documentation of the rather critical parameter "flags" was just the word "flags". I've seen cases where the return value was documented only as "status". Not even with a notion whether 0==success and 0!=failure or vice versa.

And no, it is not a closed application. They have an "extension" folder for user-supplied extensions. The problem: If it is not a core extension that has been updated with the main project, the first thing after an upgrade is finding out where your formerly working extension critical to your project now fails, because they just happened to think that the call interface for the boogaloo object need a complete overhaul. Maybe it needed an overhaul, but then at least keep the older interface alive for at least a few versions after documenting the new interface and marking the old one as deprecated.

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)

If it's all gobbledygook to you, then you weren't the target audience.

Most developers are writing for developers who have approximately the same skill level and knowledge. The vast majority of tutorials out there are definitely not aimed at beginners. They're aimed at peers who know most of the same stuff, but want to broaden their horizons a little.

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. There are way too many tutorials that have a "rest of the owl" problem at some stage. I was trying to figure out how to do something today and I must have skimmed through 30 tutorials aimed at people roughly my skill level before I finally found one that explained the missing bit. That missing bit turned out to be pretty easy, but almost every thing I read just assumed people knew how to do that part, and focused in on all the wrong things.

As for actual tutorials for beginners, the biggest problem isn't that they're badly written. The biggest problem is that they don't exist. But, to be fair, they're actually really hard to write. Explaining things requires that you really understand them well. But, when you understand them well, it can be hard to put yourself in the shoes of someone who knows so little they don't even know what questions to ask. Most computerey things are complicated enough that by the time you feel confident enough to write a tutorial, you've forgotten what it was like to be a beginner.

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#
- Beginner's are the target audience for tutorials.
  No, most of the time they're not. And you don't need to warn me that an "s" is coming.
  If they had the same skill level and knowledge then they wouldn't need a tutorial to begin with.
  Note that I said "approximately", not the identical level of skill and knowledge. It's written by a fooblorts developer who uses migwed and ghai and is now looking to connect suwdo with ugfest. If you're also a fooblorts developer who wants to connect suwdo with ugfest but you have no experience with that particular thing, then the tutorial is for you. It's not for someone who has never used any of those technologies and doesn't understand anything about them.
  No they're not
  Ah, I can see you never write tutorials, nevermind then. You have no idea what you're talking about.
Most developers are writing for developers who have approximately the same skill level and knowledge
I think you're correct about this, but I also think that's part of the problem.
On the one hand you can have technical tutorials for technical people, but to your point assuming the audience has the same skill level and knowledge is actually a mistake - no two people share the same same life, so while it's reasonable to assume a certain level of knowledge, you still need to consider that there may be gaps - small gaps but gaps all the same and that it's worth being explicit about things to avoid ambiguity. A common pitfall I see in a lot of tutorials or guides is not being explicit about file paths ("just add this to the config folder" - which folder? Where?), or not correctly steering the user towards the relevant documentation about configuration values while still expecting them to insert some config file specific to their system, stuff like that.
The other end of the spectrum - the beginner, to your point might not be the target audience but a lot of people don't realise that those folks exist. The absolute classic example I see of this is Linux for the Everyman - Lemmy is very big on promoting Linux and moving folks away from Windows/MacOS but 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. So they're both not the target audience but expected to learn that stuff - and of course it doesn't work and they stick to what they do know.
All this is to say, writing tutorials is a skill in itself and part of that skill is knowing who your target audience really is and knowing where your knowledge is his experience from working at something for so long or a basic level of understanding you expect a user to have.
- The article is by what appears to be a career writer who implies that developers should be doing their job, too. Not to mention this is mostly in unpaid FOSS. The author's method is tone deaf.
  As for your response, while factually true, to your example: Lemmy users don't care that you use Linux. Lemmy users care that you're the type of person who will educate yourself enough to learn Linux.
  Growth through learning, and part of that learning is figuring out the holes and filling them in. Heck, once Lemmy gets past that stage, we (and all those who took the plunge) will probably all move on to somewhere else.
- “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.

I really enjoy this writing style. It reminds me of what it was like reading Dave Barry’s Sort Of History of the United States when I was a kid.

To be honest I skimmed just of this, but the way my phone screen resolution caused line breaks I got to see the words "sususudododo baby" and that alone made me giggle.

Wait until they learn about kazoopi tickling lmao they are gonna need some serious blizterop after that

Unironically, sounds simple. Unless there's cmake in there, I always have some sort of trouble with that piece of garbage.