“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! 
  • @rtxn@lemmy.world
    11•10 hours ago

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

    • 💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱OPEnglish
      1•3 hours 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#.

    • EpheraEnglish
      11•9 hours ago

      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.

    • @RunJun@lemmy.dbzer0.comEnglish
      8•9 hours ago

      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.