I do read the docs. Even before trying software, to judge if ot will fulfill my requirements... Rocky Linux is one such example. Great docs, I'd love to try their distro one day :)
this post was submitted on 19 May 2025
193 points (97.1% liked)
Selfhosted
46672 readers
570 users here now
A place to share alternatives to popular online services that can be self-hosted without giving up privacy or locking you into a service you don't control.
Rules:
-
Be civil: we're here to support and learn from one another. Insults won't be tolerated. Flame wars are frowned upon.
-
No spam posting.
-
Posts have to be centered around self-hosting. There are other communities for discussing hardware or home computing. If it's not obvious why your post topic revolves around selfhosting, please include details to make it clear.
-
Don't duplicate the full text of your blog or github here. Just post the link for folks to click.
-
Submission headline should match the article title (don’t cherry-pick information from the title to fit your agenda).
-
No trolling.
Resources:
- selfh.st Newsletter and index of selfhosted software and apps
- awesome-selfhosted software
- awesome-sysadmin resources
- Self-Hosted Podcast from Jupiter Broadcasting
Any issues on the community? Report it using the report flag.
Questions? DM the mods!
founded 2 years ago
MODERATORS
Nothing teaches you what the documentation says like plowing ahead without reading it, fucking something up badly, having to crawl back to the documentation hat in hand and actually read it.
If documentation is written in a readable and confluent way, RTFM isn't such a big deal. The issue comes with overly draconian and non-confluent documentation.
Looking at you, Nix documentation
Day 564: I have become lost in the forums amidst flake debate threads. Do not search for me, it is already too late.
You got a nice guttural laugh outta me for that one.
In my experience, all the Linux documentation I have read has been written for peers of Linux developers, who are familiar with technical terminology and several concepts and steps are left out and implied rather than explained.
It’s a way for developers to ensure that Linux never receives adoption past other developers. Literary equivalent of pulling the ladder up.
who are familiar with technical terminology and several concepts and steps are left out and implied rather than explained.
Said it before and I'll say it again: had to manually install some software to make Steam tinker launch work, and the instructions for installing it were to download and prepare the GitHub folder, then "do the usual and move the completed file to ..."
Ive used git in the past and it still took me multiple minutes to figure out they meant the "make && build" command. Why was that so hard to fucking write??
Highly specialized people live in bubbles and assume that everyone else lives in their same bubble and so if someone else doesn’t understand, they aren’t worth communicating with.
load more comments
(1 replies)
I thought you wrote confluence and wanted to grab my pitchfork.
rivers
Petrichor
There is a way with chmod in bash to change files and folders with files getting no execute bit and folder do (rwX instead of rwx). It's in the man pages but good luck finding it via Google. Stackoverflow just suggests using find over and over again.
That did it for me.
Confluent?
Flowing/coming together.
I think what they are referring to are docs where pieces are explained individually, but not in a consistent or cohesive way, obfuscating use.
load more comments
(1 replies)
"F* you, I won't read what you tell me!"
- Rage Against The Manual
so rally round your PC... with a pocket KVM
I volunteer as developer for a decade old open source project. A sizable amount of my contribution is just cooking up decent documentation or re-writting old doc from the original module authors written close to a decade ago because it failed me information wise when I needed it. Programmers as it turns out are very 'eh, the code should explain itself to anyone with enough brains to look at it' type of people so lost in the sauce of being hyperfluent tech nerds instantly understanding all variables, functions, parameters, and syntax at very first glance at source code, that they forgot the need for re-translation into regular human speak for people of varying intelligence/skill levels who can barely navigate the command line.
Programmers as it turns out are very ‘eh, the code should explain itself to anyone with enough brains to look at it’ type of people
I cannot say how much I hate this.
even worse for old code where proper variable naming and underscores were forbidden. Impossible to get into someone else's head.
It's weird that Linux certification requires rote-memorization of commands. The only people who make any effort to memorize commands are newbies and people studding for exams. You will always have access to bash history, man, and --help, even from an offline machine.
Every command I've memorized is simply the natural process of repetition. Is that your experience?
Yes. But also, despite having done it literally thousands of times, I still can't tell you which way round to put the target and the link name for a softlink on the first go.
My first guess is always
ln -s $NAME $TARGET
No amount of repetition will fix this.
My trick to remember:
You can link to a target without giving a name to the link. ln will use the basename of the target file then. You can't create a link without a target, so target has to go first since it's not optional. Did it for me
I used to have that problem with ln until I realized it’s essentially the same ordering as cp: source, then destination. The source being the existing file that you’re linking to, and the destination being the link that you’re creating
I feel seen
load more comments
(2 replies)
People are worried about losing skills to AI while all the skills have already been lost to Google and stack exchange 😅
Are you trying to say I'm not a newbie with over 20 years of experience?
load more comments
(1 replies)
I worked next to a technical writer for Unix; the Unix. One of the things we were known for, actually, was the amazing documentation. This guy and both teams of writers (that many) maintained the doc as their entire job. It was written well, it was spell-checked, it was accurate, it was accessible. If you installed the machine, it was on http://localhost/doc or so.
Almost all tech writers were turfed after Y2K. They cost money and didn't earn directly.
If you notice a lack of good docco like you notice a lack of mentoring in code dev (I see you, Systemd), then we know how we got to this stage.
If you become CEO, just keep that in mind.
As a technical writer, I always get a bit giddy when someone shows appreciation for good docs haha Thanks for sharing!
Man pages tend to assume a lot and overload the user with information.
Forums are full of "duh, haven't you read the man pages, idiot?" kinds of people.
Web searches are full of AI/garbage (same thing) articles that focus on distros/programs that are either horrendously inaccurate, out of date, or simply don't exist anymore.
Therefore, I utilize the tldr man pages, and use extremely specific terms for web searches.
Oh thank hell it’s not just me. Every so often I retry the man command only to get frustrated having to flip through six walls of text via keyboard for something a 20 second Internet search would have easily refreshed my memory on.
FYI
Use / to search the man page, it's basically less. Been doing that for years, as some man pages are the length of the great wall of China.
Bingo.
And even then it's difficult to find shit, like for instance, finding the working directory for crontab when run as root. This answer on Stack Exchange is the embodiment of my second example in the other comment. The answers go into great detail, yet still don't answer the question in any reasonable capacity for a "standard user" like myself.
load more comments
(1 replies)
Man can be searched as well, if you use less or grep a lot the same keys work.
Use / to search
Yes, I am painfully aware. Unfortunately, this doesn't actually help.
RTFM. ...
... The last thing you try.
I find that the docs usually consist of a quick start guide covering some ultra tight scenario that doesn’t apply to most people, and reference material that’s just some total brain dump of every possible command without any kind of context.
Lol reading the source has trained me to try reading the documentation.
If it's good, it'll save hours or crawling through code.
Depends on what I am doing. Walky Talky? Toaster? Dish washer? ...... Who needs a manual for that?
FID detector? I need to know several things before turning it on. New Mainboard? Why is the WoL setting behind wake on PCIe?
Well, I've had a job where most coms were through a walky talky and somehow people didn't understand they had to think - push - talk 😅
Funny how that's the case for most people 🤣
While investing money to create good documentation is the preferred way, I cannot trust it to be accurate in this day and age of cutting corners. It takes a bit longer but I'll always look at the code itself to get me closest to the truth of what is going on under the hood.
I have found the docs the best place to start with anything, but have found that some don't know how to write good documentation.
Also man pages and the tools own help -? Or -h
If you run something that has pants docs, you could always see if there is a way to help update it
i stopped reading most docs after like 95 unless they are rfc or reference and i had a memory that was stellar
now, i read all of them over and over and over because i got a tbi from electroshock "therapy" and i am working with shitty autobiographical memories and cant get to the details. so i read, keep reading, and make sure all the mans are at hand along with my references. now i get frustrated and wanna die but i still get it done but im always like yeah uh no
I also don't RTFM
I would say that I RTFM about 75% of the times (give or take). Though I only do it to see if I can find something other than what I intended to use the software or hardware for.
view more: next ›