Programmer Humor

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

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.

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?

1. Turn on your computer. Make sure you turn on the "PC" (the big box part) as well as the "monitor" (TV-like part).

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

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

4. Download the software and unarchive it to a new directory in your borklaving software with the appropriate naming convention.

5. Edit the init file to match your frooping setup.

6. If you're using Fnerp then you might need to switch off autoglomping. Other suites need other settings.

7. Use the thing. You know, the thing that makes the stuff work right. Whatever.

Congratulations! You're ready to go!

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

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?

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

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.

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 envy some people's ability to come up with nonsense words.

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

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.

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

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

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

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

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

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.

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

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

Boop!

If you don't understand the "problem" part in the "what problem does this tool fix?" Then you probably don't need that tool. You should probably try the program they mentioned that didn't fix their specific problem. Since that program probably has way more users and a more entry-level documentation.

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

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.