I'm guilty of not reading the f..ing documentation
from lapping147@lemm.ee to selfhosted@lemmy.world on 19 May 18:39
https://lemm.ee/post/64407608

I’ve got to confess, I have for years been guilty if not reading the documentation. I simply go with the flow and hope it works…

But not anymore! And why the change you may ask? We’ll, I’m reading the f…ing documentation on Rocky linux and I’m just blown away from the amount of great information!

If you’ve been guilty of not reading the documentation, let me me know what changed it for you

If you’re not reading the documentation, this is your time to confess!

#selfhosted

threaded - newest

Xanza@lemm.ee on 19 May 18:52 next collapse

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.

lapping147@lemm.ee on 19 May 18:56 next collapse

You’re absolutely right

athairmor@lemmy.world on 19 May 19:41 next collapse

Confluent?

curbstickle@lemmy.dbzer0.com on 19 May 20:06 collapse

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.

RamblingPanda@lemmynsfw.com on 19 May 20:53 next collapse

I thought you wrote confluence and wanted to grab my pitchfork.

scheep@lemmy.world on 21 May 08:51 collapse

rivers

RamblingPanda@lemmynsfw.com on 21 May 09:54 collapse

Petrichor

shrugs@lemmy.world on 20 May 01:30 next collapse

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.

Custard@lemmy.world on 20 May 12:57 next collapse

Looking at you, Nix documentation

Feathercrown@lemmy.world on 20 May 14:08 next collapse

Day 564: I have become lost in the forums amidst flake debate threads. Do not search for me, it is already too late.

Xanza@lemm.ee on 20 May 22:00 collapse

You got a nice guttural laugh outta me for that one.

PerogiBoi@lemmy.ca on 20 May 13:52 collapse

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.

gamermanh@lemmy.dbzer0.com on 20 May 14:52 next collapse

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??

PerogiBoi@lemmy.ca on 20 May 16:27 collapse

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.

OriginalUsername7@lemmy.world on 20 May 18:56 collapse

XKCD 2501, basically.

PerogiBoi@lemmy.ca on 20 May 19:27 collapse

Thank you for this. It’s beautiful.

Xanza@lemm.ee on 20 May 22:00 collapse

I mean, it’s technical documentation. There’s a limit to how exciting it can be. lol.

Zwuzelmaus@feddit.org on 19 May 18:53 next collapse

What the … LOL

lapping147@lemm.ee on 19 May 18:57 collapse

Gotta start somewhere 😅

Eheran@lemmy.world on 19 May 18:56 next collapse

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?

lapping147@lemm.ee on 19 May 19:00 collapse

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 😅

jjlinux@lemmy.ml on 20 May 11:22 collapse

Funny how that’s the case for most people 🤣

cron@feddit.org on 19 May 19:16 next collapse

I mostly try to read the docs, but sadly good documentation is pretty rare.

tisktisk@piefed.social on 19 May 19:20 next collapse

well I'd read the documentation if websearch wasn't so shoddy that I could find it in the first place /s

sixtoe@lemmy.blahaj.zone on 19 May 19:27 next collapse

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

sunzu2@thebrainbin.org on 19 May 19:31 next collapse

I prefer to raw dog it first, break it, then tuck me dick and read the paper like the real alpha male

irmadlad@lemmy.world on 19 May 23:36 collapse

I’m kind of that way. I will browse documentation, get a good idea as to what has to happen, then I raw dog it. Then, after many failed attempts, I go read the documentation. I agree with twinnie@feddit.uk tho, a ton of documentation either assumes you are a certified, dyed in the wool, sysadmin veteran with a wall of certs, or it’s just too sparse for me to put together.

shrugs@lemmy.world on 20 May 01:46 collapse

I have a theory: information is best remembered if it is acquired solving a problem.

Play with the new tech, hit a roadblock, read and learn. That way you are motivated, know why you are reading the stuff and also only learn the stuff that isn’t intuitive.

Depending on experience many things are just like something you already know and easy to learn/remember, others are not. Don’t waste your time learning the first.

On the other hand, put me into a room with a teacher, who tries to teache me specifics about a tech I don’t care about and I will promise you, I will learn nothing. Even worse, I will start to hate that tech.

irmadlad@lemmy.world on 20 May 14:18 collapse

On the other hand, put me into a room with a teacher, who tries to teache me specifics about a tech I don’t care about and I will promise you, I will learn nothing. Even worse, I will start to hate that tech.

Interesting. I read a lot. Probably tb’s of data per day. I don’t watch tv not even news or weather. It’s not a religious thing and it doesn’t make me holier than thou. I just find that reading is best for me. However, if you hand me a traditional book, I will never crack the binding. Put that same book in a digital format that I can read from my devices, and I’ll read it cover to cover and probably storage the document to read later.

We’re all kind of quirky and we all have our own optimum way to learn. Mine is usually just screwing shit up until I get it.

shrugs@lemmy.world on 20 May 14:26 collapse

Same for me, no TV for the last 15 years. All I consume is online and about topics I like.

TBs of data per day? You know how much text fits into 1tb? o.O

Anyway, we seem to enjoy a pretty similar type of entertainment. For me, it’s all about liking what I do. I can’t stand doing things I dislike at all.

Lemme ask you about ADHD?! I’m pretty sure I have it but don’t care. I am who I am. How about you?

irmadlad@lemmy.world on 20 May 15:07 collapse

Lemme ask you about ADHD?! I’m pretty sure I have it but don’t care. I am who I am. How about you?

I’ve long been told that I have the tenants of ADHD. When I was a young lad, ADHD was not something that doctors looked for. Then as time progressed and we learned a lot more about ADHD, and two lines of thinking emerged. Either ADHD is a real illness, or it was bunk science. Nowadays, we know a ton more about these kinds of mental maladies and I truly feel that more people than what we realize are on the spectrum.

I have had a TBI which gifted me a seizure condition as well as other mental/neuro maladies. I’m sure a lot of my issues stem from the TBI as well. It has definitely made drastic changes in how my brain works and sometimes the most simplest of tasks are hard for me to comprehend. However, after falling from 2 stories onto a concrete pad and laying there in a pool of blood for an unknown amount of time before someone found me, I feel quite fortunate to be alive.

yesman@lemmy.world on 19 May 19:33 next collapse

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?

RamblingPanda@lemmynsfw.com on 19 May 20:52 next collapse

Are you trying to say I’m not a newbie with over 20 years of experience?

med@sh.itjust.works on 19 May 23:19 next collapse

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.

turkalino@lemmy.yachts on 20 May 00:27 next collapse

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

shrugs@lemmy.world on 20 May 01:33 next collapse

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

Bo7a@lemmy.ca on 20 May 10:23 next collapse

What about substitution in your mind.

My way is probably not going to help but it might.

I see ln -s in my mind as the word link. And the sentence in my head is ‘link THIS HERE’ where ‘this’ is the source and ‘here’ is the target

mvirts@lemmy.world on 20 May 16:12 next collapse

🤣 same

qqq@lemmy.world on 20 May 22:52 collapse

I feel seen

LucidNightmare@lemm.ee on 20 May 16:10 next collapse

Mine too. Been tinkering with Linux since I was a lad, sudo apt get / sudo apt update is ingrained into my brain.

Now, after running openSUSE Tumbleweed, sudo zypper ref / sudo zypper dup

Still a Linux noob, but I have never loved an operating system more than I have openSUSE. :)

mvirts@lemmy.world on 20 May 16:14 collapse

People are worried about losing skills to AI while all the skills have already been lost to Google and stack exchange 😅

lka1988@lemmy.dbzer0.com on 19 May 20:25 next collapse

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.

Broadfern@lemmy.world on 19 May 20:38 next collapse

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.

bigredgiraffe@lemmy.world on 19 May 20:46 next collapse

Oh it is certainly not just you, I am sometimes confused reading them even for commands I have used for years and I know what flag I am looking for but don’t remember the exact syntax or something hah! I am glad they are there but they are definitely not a complete guide to any command, especially built-ins.

Interestingly, this is something AI has been very useful for to me, less searching because I can describe the outcome I want and it figures out what I am talking about generally.

lka1988@lemmy.dbzer0.com on 19 May 21:01 next collapse

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.

mhzawadi@lemmy.horwood.cloud on 20 May 05:51 collapse

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.

mhzawadi@lemmy.horwood.cloud on 20 May 05:52 collapse

Man can be searched as well, if you use less or grep a lot the same keys work.

Use / to search

lka1988@lemmy.dbzer0.com on 20 May 05:58 collapse

Yes, I am painfully aware. Unfortunately, this doesn’t actually help.

Flyswat@lemmy.dbzer0.com on 19 May 21:08 next collapse

"F* you, I won’t read what you tell me!"

  • Rage Against The Manual
AmazingAwesomator@lemmy.world on 19 May 21:24 collapse

so rally round your PC… with a pocket KVM

twinnie@feddit.uk on 19 May 21:53 next collapse

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.

irmadlad@lemmy.world on 19 May 23:19 next collapse

Oh it happens to the best of us. I was working on a simple cron the other day with the cron string that would insert the cron into my cron config something like ‘echo’ and the normal string you’d recognize, and ended with a ‘-’. I wasn’t paying attention and issued the command which did insert itself into the cron config, but in a manner in which I didn’t want. It replaced the whole cron file with that one string. #$@^$$ Luckily I have a cron to back up the crontabs.

pineapplelover@lemm.ee on 20 May 01:57 next collapse

I also don’t RTFM

jjlinux@lemmy.ml on 20 May 11:21 collapse

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.

mhzawadi@lemmy.horwood.cloud on 20 May 05:54 next collapse

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

Smokeydope@lemmy.world on 20 May 06:28 next collapse

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.

PoisonedPrisonPanda@discuss.tchncs.de on 20 May 22:33 collapse

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.

corsicanguppy@lemmy.ca on 20 May 06:46 next collapse

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

JigglypuffSeenFromAbove@lemmy.world on 20 May 11:50 collapse

As a technical writer, I always get a bit giddy when someone shows appreciation for good docs haha Thanks for sharing!

melsaskca@lemmy.ca on 20 May 12:21 next collapse

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.

mvirts@lemmy.world on 20 May 12:40 next collapse

Lol reading the source has trained me to try reading the documentation.

If it’s good, it’ll save hours or crawling through code.

flop_leash_973@lemmy.world on 20 May 14:27 next collapse

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.

dbtng@eviltoast.org on 20 May 17:26 next collapse

RTFM. …
… The last thing you try.

anzo@programming.dev on 22 May 21:54 next collapse

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

friend_of_satan@lemmy.world on 25 May 13:09 collapse

I had a boring manufacturing job with long gaps between batches of work, so I read every help file in Windows NT4.1. While reading it, I found a way around our IT limitations on which apps we could run, and learned how to write scripts. So I wrote a password protected launcher tool using a macro feature in a terminal emulator I had access to on my workstation, and then started reading the man pages in Unix sys-V.