“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!
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
bpymodule, 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().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.
IBM
Microsoft
Apparently so.
Except the manuals are written like this, and don’t cover pre-requisite knowledge at all - don’t even link to it!
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 writing good documentation
But you can certainly expect them to link to resources about pre-requisite knowledge, like I did in Creating MAUI UI’s in C#.