558
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
this post was submitted on 25 Sep 2025
558 points (95.6% liked)
Programmer Humor
26674 readers
1758 users here now
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.
Rules
- Keep content in english
- No advertisements
- Posts must be related to programming or programmer topics
founded 2 years ago
MODERATORS
I think you're correct about this, but I also think that's part of the problem.
On the one hand you can have technical tutorials for technical people, but to your point assuming the audience has the same skill level and knowledge is actually a mistake - no two people share the same same life, so while it's reasonable to assume a certain level of knowledge, you still need to consider that there may be gaps - small gaps but gaps all the same and that it's worth being explicit about things to avoid ambiguity. A common pitfall I see in a lot of tutorials or guides is not being explicit about file paths ("just add this to the config folder" - which folder? Where?), or not correctly steering the user towards the relevant documentation about configuration values while still expecting them to insert some config file specific to their system, stuff like that.
The other end of the spectrum - the beginner, to your point might not be the target audience but a lot of people don't realise that those folks exist. The absolute classic example I see of this is Linux for the Everyman - Lemmy is very big on promoting Linux and moving folks away from Windows/MacOS but there's a bit of a disconnect because a lot of tutorials exist that base level of knowledge that a complete beginner doesn't have. So they're both not the target audience but expected to learn that stuff - and of course it doesn't work and they stick to what they do know.
All this is to say, writing tutorials is a skill in itself and part of that skill is knowing who your target audience really is and knowing where your knowledge is his experience from working at something for so long or a basic level of understanding you expect a user to have.
The article is by what appears to be a career writer who implies that developers should be doing their job, too. Not to mention this is mostly in unpaid FOSS. The author's method is tone deaf.
As for your response, while factually true, to your example: Lemmy users don't care that you use Linux. Lemmy users care that you're the type of person who will educate yourself enough to learn Linux.
Growth through learning, and part of that learning is figuring out the holes and filling them in. Heck, once Lemmy gets past that stage, we (and all those who took the plunge) will probably all move on to somewhere else.
Paid documentation writers at Microsoft are absolutely horrible at it too. That's why I can relate to the post so much
This is one of the biggest problems with Microsoft documentation (and maybe other ecosystems too). Doesn't include any "using" statements in the snippet, leading to copying the code not working, because you don't know what DLL this is using. They talk about 2 lines, and show you 2 lines, but the 2 lines don't work without 1 or 2 other lines which they have left out. Happens every single time
Microsoft documentation never links to anything else at all. If you don't know how to do this thing they're talking about, well now you have to go find a Youtube by some Indian programmer about it
Yep. The man pages are so not user-friendly. I have always said that Unix is very powerful, but not the least bit user-friendly. Welcome to low adoption.