I think the blogger is more technical than they let on:
- understands how to write footnotes
- structures lists correctly
- runs their own blog with custom domain name.
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”.
understands how to write footnotes
x
The footnotes link to the list instead of the actual footnotes. I was quite confused.
Looks like a case of broken web browser or doesn’t understand footnotes. 🤔
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
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
As a developer, that is also how I read tutorials written by other developers.
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?
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.
Thank you for that. I’m sure the people who read it and got a grasp of what they are trying to accomplish greatly appreciate your going out of the way like that. :-]
Usually it’s to help a customer create a proof of concept going so we can make a sale so it’s not entirely a selfless act.
Plus it keeps me from sitting on hours-long calls trying to walk them through ambiguous instructions.
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!
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.
Oh do grow up, frankly.
When I taught myself to program, there was no internet. You went and bought an enormous, 800 page book (usually written by Charles Petzold) and you hoped to Darwin something, anything would be understandable and lead you to move forward just a little bit.
If it’s worthwhile doing it’s hard.
You recognize the feelings of the author and relate to them personally with Charles Petzold’s writing from back when, and say they need to grow up?
I think it’s a little reductive to say the author just wants everything to be easy.
Help me understand what the author is trying to say, please. It could be I’m missing something. It just reads to me like the author feels everybody else has a responsibility to somehow make complicated topics easy.
a responsibility to somehow make complicated topics easy
That’s what tutorials are for! 😂
Some topics are just complicated. If I write you a tutorial in fast Fourier transforms I can’t start the tutorial at 1+1=2.
I can’t start the tutorial at 1+1=2
But you can put it in the pre-requisites
Of course. But that wasn’t the complaint/satire of the satirist whose article we’re discussing.
Of course. But that wasn’t the complaint/satire of the satirist whose article we’re discussing
I think you’ll find that’s a huge part of the complaint - unexplained terminology. See Microsoft tutorials that never tell you what any of their TLA’s are, nor link to any explanations of them, exactly as is satirised
usually written by Charles Petzold
Classic example of someone who wrote tutorials like the type being satirised.
If it’s worthwhile doing it’s hard
Writing good tutorials isn’t hard. You just have to not assume background knowledge of anything you’re writing about. If you write it for beginners, then literally anyone can follow it.
So maybe the tutorial the satirist was satirising just wasn’t quite aimed at the satirist.
So maybe the tutorial the satirist was satirising just wasn’t quite aimed at the satirist
I think many people here have seen exactly such tutorials - indeed aimed at them - hence the huge upvotes. See Microsoft tutorials that never link to any pre-requisites at all (leaving you looking for a Youtube by an Indian programmer).
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?
-
Turn on your computer. Make sure you turn on the “PC” (the big box part) as well as the “monitor” (TV-like part).
-
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”.
-
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.
-
Download the software and unarchive it to a new directory in your borklaving software with the appropriate naming convention.
-
Edit the init file to match your frooping setup.
-
If you’re using Fnerp then you might need to switch off autoglomping. Other suites need other settings.
-
Use the thing. You know, the thing that makes the stuff work right. Whatever.
Congratulations! You’re ready to go!
Sounds like typical Microsoft documentation to me. Explains in great detail what .NET is, where you can download it from, then jumps straight to the advanced topic they’re covering without any of the intermediate knowledge covered or even linked to (but perhaps referred to only vaguely in passing as an acronym, again with no link, this time no link to what “TLA” is actually short for, so you’re searching for it is fruitless as well).
I think TLA means “Three Letter Acronym” in some circles. So like, DBA would be a TLA meaning “database administrator” for example. Didn’t read the article to get the context though, so not sure if it fits
Yes, TLA is a three letter acronym. A four letter acronym, on the other hand, is an ETLA, or “Enhanced Three Letter Acronym”. For advanced cases, you can get an EETLA (or XETLA) for Expanded/Extended Enhanced Three Letter Acronym.
Just so you know.
I think TLA means “Three Letter Acronym” in some circles
Yes, that was why I used it. Microsoft doco is full of unexplained TLA’s - you have to already know what it means and how to use the thing. You knew what TLA meant. Now read the Miscrosoft doco where you don’t know what any of the MS TLA’s mean, and they don’t tell you.
Too real.
-
People say “RTFM” then you get to the manual and it’s this
Microsoft Manuals…
That is spot on. Usually you would expect the manual to be hit and miss when it comes to troubleshooting but Microsoft is consistently miss, skipping the important parts and details.
Microsofts documentation is also increasingly just outright wrong:
if you spend enough time looking up things about their newer products like M365, defender, or azure, especially when it comes to scripting related to those, there’s a ton of simply outdated info on the official docs that makes it really difficult to figure out why your setup isn’t doing what it’s supposed to.
from changed variable names, to missing functions, to unexplained buttons, etc., etc.
the newer docs are straight up trash!
you’re better off searching around for forum posts or whatever, than using the official docs…
Microsofts documentation is also increasingly just outright _wrong_:
There used to be a spot on joke about Microsoft documentation taking the piss out of the fact that it was always 100% accurate but at the same time pretty useless. That joke hasn’t been relevant for a while.
It’s so frustrating trying to find out how to do something in one of the admin centres for M365 and you find a Microsoft document with exactly what you need in it only to find out that the UI has changed and the steps don’t work now. Did they move it? Did they remove it? Who knows?
our admins are regularly straight up fighting against this bs!
“where the fuck has this fucked off to now?? it was right here last month?!”
so glad I’m not doing MS administration…
If you are used to documentation like MS’s, then AI responses probably look more reasonable and useful. If AI results look better than your own docs you should feel really bad.
this is the part that’s really frustrating:
i sometimes feel forced to use chatGPT (duck.ai) to simply search for Microsoft things, because search engines only return SEO garbage with the exact same content spammed across like a million “tech tips for beginners” sites…and the docs, as established, are pretty useless…
keep in mind: i fucking hats “AI”.
making me use it makes me not have anything to do with whatever you’re selling.
it’s getting progressively more impossible to simply use MS products, because the information you need to use them is so hidden away!
combine those two things and ta-da: that’s why all my stuff at home is running linux now.
Amazon is no better. Go look up the correct parameter format required to set a compliance lock on an object in S3 via the API. Now try it yourself. Surprise!
you’re better off searching around for forum posts or whatever, than using the official docs
Yep, that’s why I started the Lemmy .NET MAUI Community - try and reassemble the collective experts who got scattered when Microsoft shutdown the old Xamarin forum - they had been invaluable when I was trying to learn Xamarin from the Microsoft resources.
oh hey, that’s great! thank you!
Also, requiring login.
Basically Hello World using the win32 API. I believe I first encountered this before college, and it took actually professional dev experience to really understand it.
Link 1: Pencil selection guide Link 2: Ovals vs. circles Link 3: Wings Link 4: Bird feet
Another problem is that people skim to the “most important bits” without knowing they’re skipping something important. Then some of those people complain how the manual is shit.
I guess it could be shit if it is way too verbose though.
Exactly what I was thinking. Like needing to understand a huge preamble just to do the Very Simple Thing. I just want to move on, not marry this Linux command.
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.
Pretty sure every tech person at some point or another has had to do exactly that. And not just their mom, but their dad, and their extended family, and their parent’s friends who have a random problem, etc
Sometimes it’s not user friendly, other times it’s not friendly users.
And why? Because none of them can read the fucking manual! And you’ll say they don’t try, but many of them have tried. Once. And all they learned was that it wouldn’t do them any good.
Because the manual often doesn’t cover what they’re trying to do, or finding reliable information online is it’s own struggle.
In my case it’s usually “can you help me undo what my cat did?” Treading the keyboard with 4 paws enables her to work wonders it would usually take 2 NCIS agents typing on the same keyboard to accomplish.
I taught basic computer literacy. I am a software developer. It’s tough to reframe my own knowledge so drastically, but the new perspective also makes me question why so many things are wrong with current tech (particularly UI/UX).
Oh definitely, there’s so many products we use that are far more complicated than they have any need to be.
Vehicles and appliances are two examples that come to mind.
My peeve is products made “easy” to use, in a way that makes explaining them extremely difficult. Two top examples are:
URL bar in browsers which doubles as a search bar. Good luck explaining why if you type in an exact existing address, you will get there, but otherwise (typo, extra space), you will end up on Google.
Apple’s iMessage. Your message will be sent to your contact using one of three protocols: SMS/MMS, iMessage or RCS. This is almost entirely opaque, and I even had to explain to a tech-savvy person why videos they send me look like blobs.
I think the issue is that you need to understand who your users actually are. Documentation for a library intended to be used by a reasonably competent software engineer is going to have different requirements vs documentation for a cli utility aimed at Arch btw Linux users vs documentation for a program to help Grandma organize family photos.
If you throw a terminal command at Grandma she’s going to panic and call her grandchild. If you put instructions for extracting a tarball in your library docs the programmer is going to get bored and skip ahead.
I just want a friendly user :(
I envy some people’s ability to come up with nonsense words.
Like the Turbo Encabulator
You might enjoy [email protected]~
Galabrup, anyone?
I prefer Fizkada more.
Sternocleidomastoid, oh wait, that’s a word. Dang it.
How about Bifurcation😅
This is a much harder game for Germans.
Ponblopdring!
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
-
