Welcome to Programmer Humor!
This is a place where you can post jokes, memes, humor, etc. related to programming!
For sharing awful code theres also Programming Horror.
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
Actually!
I went to the comments expecting some more jokes but found multiple dissertations instead wtf.
Yooo, seriousely whats going on?? Hahaha
I think the blogger is more technical than they let on:
I've known programmers struggle with markdown.
Well that's because markdown is for documentation, and we all know programmers don't know how to write documentation.
Documentation goes in the commit message.
That way you know when it was correct, because the next commit immediately makes it stale.
🥲
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".
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.
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
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.
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.)
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?
As a developer, that is also how I read tutorials written by other developers.
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.
When it comes to documentation, at least for myself when I'm learning new things, I like to look at it like a recipe book.
The book shouldn't contain just the ingredients and what the final product looks like. It needs to be more in depth than that. It needs to contain the ingredients that go into it, how much of those ingredients, the time to cook, what consistency to look for, prep time, etc.
There are plenty of people out there who have never cooked before, and a recipe book/instructions on how to cook a favorite dish is the perfect way to share your love of the craft and the dish that you made. Then, with your recipe as a guideline, people could change it to suit their tastes, and so on and so on.
That's just how I look at it. I wish I could interpret developer instructions and write up a more user friendly documentation for them. I would love to be able to give back to the community in some more meaningful way than just barely knowing what the developer is providing and using it and making a mess of it my first few tries until I learn from my mistakes.
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.
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
This is one of those things where I'm actually okay with AI use. I understand a lot of the FOSS community devs don't have a lot of time for such matters, so if this gets it at the very least 90% there, I would consider it a win! (human review being a big bonus, of course!) :-]
Boop!