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.

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

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

Like the Turbo Encabulator

Galabrup, anyone?

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

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!

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.

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.

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.

Actually!

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

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

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

understands how to write footnotes

x

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

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

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.

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.

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.

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

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

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#

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.

Haha yeah, made me think of escape sequences

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)

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

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.

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.

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

Beginner's 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#