Mina

documentation is absolutely undervalued and unappreciated by *nix users.
they love feeling like wizards who know all the arcana.

why else would they flock to a system as horribly documented at Linux?

if i want to know how something works, i read a Solaris or BSD man page.

if i want to feel stupid i can read a Linux man page. if i want to feel utterly frustrated i could try to read the GNU info page.

if i want to feel hopeless, i can read a venture capital funded corporate open source tool's documentation website.

Jun 14, 2022 at 5:35pmWeb
Show threadgo͚ktu͠gJun 14, 2022

@meena this is kinda humblebrag but my dotfiles have much better documentation than most FOSS projects out there and that should mean something.

like I wrote all this code myself for myself, it's mostly very simple stuff, but without comments and without documentation I myself would forget 90% of it, let alone others.

Show threadGreyshley Jun 14, 2022
@meena more BSD praise.
I'm getting curious now.
Show threadUnattributed 👤 ☑Jun 14, 2022

@meena It's unfortunate that many of the open source projects don't seem to attract people that are willing to do the work of documenting the systems / applications that are being written.

Some of the best applications have the best documentation... For example LibreOffice.

If projects spent as much effort attracting people that can write professional documentation as they do programmers, designers, and technical people, we'd be alot further.

Show threadLudovic Archivist LagouardetteJun 14, 2022

@meena I can quote every single word of the C and C++ ABI docs on Linux:

That's it. Can't do that on OpenBSD or Windows though, too many words

Show threadVulture CultureJun 14, 2022
@meena really out of my depth here, guess I just wanted to say that with the CW, I thought this post would be about how toothpicks are better or something
Show threadMinaJun 14, 2022
@vultureculture thanks
i… i should actually floss my teeth.
Show threadVulture CultureJun 14, 2022
@meena 9/10 dentists would approve of this message
Show threadYogurtCommuteJun 15, 2022

@meena 💯

I still use the FreeBSD handbook and OpemBSD man pages even though I now work at a Linux shop.

`man x` just doesn't cut the mustard. Even worse is how often `apropos` fails to find anything helpful 😭

Show threadaurorusJun 15, 2022
@meena @mwlucas if they’d document linux, it would be obvious, how much is so badly designed. If you’re into horror, compare how to atomically change firewall rules for pf and iptables. And then look how it’s actually done, in e.g OpenWRT.
Show threadamirouche 🌱Aug 22, 2022

@meena

magic is absolutely hypervalued.