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

[–] Ephera@lemmy.ml 19 points 3 days ago (1 children)

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.

[–] SmartmanApps@programming.dev 0 points 2 days ago

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.

[–] RunJun@lemmy.dbzer0.com 13 points 3 days ago (1 children)

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.

[–] SmartmanApps@programming.dev 1 points 2 days ago

There’s amazing

IBM

and terrible manuals everywhere.

Microsoft

[–] SmartmanApps@programming.dev 2 points 2 days ago* (last edited 2 days ago)

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