|
> where the official documentation isn’t monumentally better than every other option 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: <huge paragraphs telling me shit I already know, that rsync transmits files> <-A does some obscure, esoteric thing that I dont care about> <-a does almost the same thing as A, but was kept for "Sys-V compatibilty, deprecated"> <-b ....>
...
<-r getting close,> <-s ah , secure mode> . 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. <-n> 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" |