25 Years Later: Interview with Linus Torvalds

In case you are actually interested and don't just want to support a certain political position, this could be a quick introduction: https://en.wikipedia.org/wiki/Paradox_of_tolerance

Man, opposite experience here. I will cheerfully admit to being way less smart than most HN users, but I find that official documentation almost always lacks egregiously in example code, and also in overview material that gives me a 30,000’ view of the product. So often documentation seems assume that I’m already familiar with the product, when sometimes I’m dropped in for some external reason and just want to get a job done without being an expert.

You should have made an effort in fixing grammar in the above sentence before putting people down like that. At least, they are trying and not giving up. That's commendable

I don't mean the search results that point to Stackoverflow, which are usually common patterns/answers. I mean looking up official docs, reading the code, just trying things without immediately looking for someone to handhold you through everything. You don't need to read medium articles or watch youtube for every single thing. Even a lot of tech conferences are full of talks going over the same basics over and over again, and these are meant for programmers.

This is a result of social media proliferation and the desire to do everything online and enhance your profile instead of just getting some work done. Y

Let me tell you my problem with documentation, with this example (embellished to emphasize my point): say you're looking at the man page for this new, unfamiliar linux command `abc`. Here, "a b c d e f g h i j k l m n o p q r s t u v w x y z". That's the documentation, in fact it's the documentation for ALL linux commands. What's wrong? Can't make `abc` work for your use case? OH, that's your fault because you didn't know the one particular sequence to arrange those 27 characters (include the space) to actually give you the information you need. You just didn't read hard enough. I mean, there's only 36^2000 or so combinations. Just keep arranging them until the letters spell out the answer to your query!

Thats why SO is way more popular than RTFM. TFM never tells me what I want. They tell me an encyclopedic, exhaustive treatise on `abc`. They don't tell me something helpful, examples on how to use `abc` to get me from point A to point B.

Here's a toy example, I wish I could think of a real one but I'm on the spot and can't recall somthing concrete, but this happens to me constantly. Also, disclaimer: no matter what example I give, someone is going to shoot me down by searching the man page and 'proving me wrong', but I've been Linux-ing for 20 years and I can't tell you a single time a man page has helped me. Generalize with me here, and dont focus on this command in particular. Say I want to use rsync and ssh. Yeah I know about scp, but there was just an HN discussion a few days ago about how that's "bad", so unless I remember their commands, I might think, "ah, I'll just read the handy rsync man page and that will show me how". Now, here's what actually happens:

man rsync:

...

. ok cool, but in all likelihood, it wont tell you HOW to use secure mode. just that -s turns secure mode on. ok, do I just tap -s and magically rsyncs are now secure? Oh, HELL NO! no, no no. First, you have to know that -s has to go before the file you want to transmit. Should the man page tell you that? oh, HELL NO! They'll just let you type it wrong, get the error, and get really frustrated (or just go to google and type "how to rsync+ssh " and get the answer immediately). so going back to my "arrange the letters" analogy, you just have to arrange the -s before, after, or in between the options until it works. The man page is USELESS.

Again, this isnt intended to be a real example. I don't know what -s does for rsync. But I DO know if I were to try to read the rsync man page to do rsync+ssh, without fail, any options documented will not work or do what I want them to, usually because the order they are typed or the format of their arguments are conveniently omitted from the so-called documentation. I used to think it was my fault for pathologically composing the args wrong, but I've come to realize it's that the docs are written by people who already know or wrote the commands, so they omit the most obvious steps, or they don't "test" the man pages (which, arguable for FOSS, maybe they shouldn't. But it doesn't change the fact that the documentation sucks).

Me: "which president authored the New Deal?"

Man page: "`presidents`, displays a complete biography of all US presidents.

displays the biography of the n-th president. Note, to increase frustration levels, search functionality is disabled for this page. If you want to find out about a specific president, you can just start at 0 and read all of their biographies until you find what you need.

me: "maybe the answer is on SO."

smug hackers: "what a noob, people don't even read the docs these days"