4 ms·

The issue I have with this kind of projects is that people quickly accept that reading manpages is boring and that they should only use `tldr gcc` or a quick st

by hk__2 11y ago

The issue I have with this kind of projects is that people quickly accept that reading manpages is boring and that they should only use `tldr gcc` or a quick stackoverflow lookup instead of actually learning how to use their tools. It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket.

gexos 11y ago
"It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket." +1 Comment of the day.
coldtea 11y ago
>It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket If you're already down to the command line, running UNIX commands, and using TLDR you are way beyond "buying fish at the supermarket". And why should you "learning how to use those tools", when what you really want from those tools are the use cases TLDR already covers?
- jordanpg 11y ago
  Agreed 100 times over. My eyeballs are strained from rolling every time I read some very sage person on SO or HN reply to a well-phrased question or comment with a terse "it's all in the docs". As if 90% of use cases aren't covered by 5 examples. As if we all have unlimited time to spend on reading docs and manpages and "learning how to use the tools". As if there is some intrinsic virtue to "learning how to use the tools". As if the very purpose of sites like SO are something other than distilling the information in docs into some other, more readable form. As if there are no man pages or docs that are absolutely incomprehensible and worth ignoring. No, sorry, this attitude is just another manifestation of standard tech machismo: "real men do it the hard way". Good luck with that!
  - moron4hire 11y ago
    Shit, I meant to upvote you, but I flubbed my phone and hit the down arrow instead. HN must think this is a feature, considering how long it has been a probelm. But I agree completely. The entire point of computers is doto mechanize doing things, to essentially be "lazy", aka more efficient.
  - hk__2 11y ago
    I’m not saying you shouldn’t use TLDR or StackOverflow. I’m just saying you could benefit from reading the manpage once instead of TLDR 10 times a day. That doesn’t mean you won’t forget most of the stuff and will use TLDR/SO to find it again but at least you’ll be more comfortable using the tool. In the `tar` case if you know what c, x, v, z and f stand for you can cover 99% of the tar use cases because those can be combined. You learn 5 letters and have now access to 8 different commands (`{c,x}[v][z]f`). Learn one more letter, `t`, and you can combine it with your existing knowledge to have 3 more commands (tf, tvf, tzvf).
    - ryandrake 11y ago
      Great. Then put those options near the top. Why are options on man pages organized alphabetically? What common use case drives that decision?
      - hk__2 11y ago
        Well, in a dictionary words are not listed at the beginning. The alphabet itself doesn’t have the most common letters at the beginning. What we should do is put the manpage examples at the beginning instead of the end.
  - nalck 11y ago
    The purpose of documentation is to describe the software. It's not machismo, it's the complexity inherent in the system. The man page for tar isn't poorly written, tar has just accrued many options. Of course there may be unhelpful answers to requests for help. It may also be that industrial technology (Unix) is not as simple or easy to use as consumer technology. Tl;dr: Blame the software stack.
deleted 11y ago
[deleted]
manigandham 11y ago
How is this much different from today? plenty of people just learn what they need from Google for their use case without reading through man pages and understanding every option. If you need more than the supermarket... then learn how to fish?
beshrkayali 11y ago
That's true, but I don't think it'd be a problem since you won't be able to really understand how something works and eventually you'd not know how to use the thing. There's always a wrong way to use something. The good thing is that this is not being promoted as a replacement, but rather a helpful addition. I see it very useful as an alternative to hunting down for tutorials before you want to use some tool to figure out the details (a good example in this case would be something like lxc/lxd) or as a quick memory jogger, the examples that can be provided in a tldr man page could even have a specific context, like a cheatsheet kind of a man page.
kbart 11y ago
Continuing your tool analogy, if I used a hammer only to drive a nail, why would I need to read the whole manual of building a wooden house? Knowing your tool is important, but I find myself spending way too much time reading manpages and looking for how to accomplish a trivial task on Linux, so TLDR for most common (simple) use cases looks like a great idea.
- hk__2 11y ago
  Reading the manual once will save you a lot of time reading TLDR over and over. Which is not to say you won’t read it; but you’ll read it less than without reading the manual first.
  - msvalkon 11y ago
    I find this hard to believe. You probably need to read the man page and perform the action over and over again. At least personally, I need to do thing X and to achieve that I know I need to use tool Y. I read the man page of Y and very satisfyingly do the thing X. A month from now I have to do something similar to X and cannot for the life of me remember what freakish incantations need to be performed in order to do the same thing so I have to go through the man page again. This is where I'd like the tl/dr of it. I don't need Y often enough to actually warrant spending much time on learning to use the niche cli it requires..
  - kbart 11y ago
    I doubt that. I don't try to memorize commands (even more so - manuals), so it's more like I'm reading manual over and over again, which takes more time than reading TLDR. I agree that it's important to understand what command is used for and what capabilities it has, but trying to remember all these flags by heart is waste of limited brain resources imho.
logingone 11y ago
I was surprised the other day when I was reading something about containers, and the author explained what the touch command does.
iamtew 11y ago
Agreed, currently the pages only show quick syntax examples, would be good to have a brief description of the tool and what it does. Also perhaps have a tldr page on how to read man pages could be useful. Or this: http://www.tfug.org/helpdesk/general/man.html http://www.tfug.org/helpdesk/general/man.html
ZenoArrow 11y ago
Nobody can be an expert in every single tool they use, furthermore it's a waste of time if you have the option of learning things when the need arises. Not only would you have forgotten most of the text of man pages after reading it, you're also unlikely to ever use most of the options you found in them. The important first step in learning how to use a command line tool is to have a first working example, i.e. you've made the tool do something you wanted. From there, all you need to know is how to find out more about what it can do. Skim read through some examples, anything else you think could be useful? Try it out. The rest can be forgotten. There's no harm in keeping knowledge outside our memory if we know how to research it if needed.
lunchbox 11y ago
Yes but overall, isn't it better to at least have the choice to go to the supermarket? (As you kind of acknowledge in your own example.)
- hk__2 11y ago
  Yes I’m not saying you should never use tldr or similar tools; just that you could benefit from reading the manpages from time to time. I learnt more things from reading `man bash` than from any StackOverflow question or post on the Web.
nommm-nommm 11y ago
Thats like saying you dont know how to fish unless you learn the detailed operation of 10 different types of fishing boats. None of which you have access to, you're fishing from the dock and your budget is $20.
- hk__2 11y ago
  > Thats like saying you dont know how to fish unless you learn the detailed operation of 10 different types of fishing boats. No, that’s not like saying that. `man tar` tells you which option to use for each use case; not the detailed algorithm of each compression algorithm.
wtbob 11y ago
> It’s like learning how to fish vs. bying fish at the supermarket. And then there are the sad misguided souls using fish as their login shells (I kid, I kid…).

by hk__2 11y ago

gexos 11y ago

"It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket." +1 Comment of the day.

coldtea 11y ago

>It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket If you're already down to the command line, running UNIX commands, and using TLDR you are way beyond "buying fish at the supermarket". And why should you "learning how to use those tools", when what you really want from those tools are the use cases TLDR already covers?

jordanpg 11y ago
Agreed 100 times over. My eyeballs are strained from rolling every time I read some very sage person on SO or HN reply to a well-phrased question or comment with a terse "it's all in the docs". As if 90% of use cases aren't covered by 5 examples. As if we all have unlimited time to spend on reading docs and manpages and "learning how to use the tools". As if there is some intrinsic virtue to "learning how to use the tools". As if the very purpose of sites like SO are something other than distilling the information in docs into some other, more readable form. As if there are no man pages or docs that are absolutely incomprehensible and worth ignoring. No, sorry, this attitude is just another manifestation of standard tech machismo: "real men do it the hard way". Good luck with that!
- moron4hire 11y ago
  Shit, I meant to upvote you, but I flubbed my phone and hit the down arrow instead. HN must think this is a feature, considering how long it has been a probelm. But I agree completely. The entire point of computers is doto mechanize doing things, to essentially be "lazy", aka more efficient.
- hk__2 11y ago
  I’m not saying you shouldn’t use TLDR or StackOverflow. I’m just saying you could benefit from reading the manpage once instead of TLDR 10 times a day. That doesn’t mean you won’t forget most of the stuff and will use TLDR/SO to find it again but at least you’ll be more comfortable using the tool. In the `tar` case if you know what c, x, v, z and f stand for you can cover 99% of the tar use cases because those can be combined. You learn 5 letters and have now access to 8 different commands (`{c,x}[v][z]f`). Learn one more letter, `t`, and you can combine it with your existing knowledge to have 3 more commands (tf, tvf, tzvf).
  - ryandrake 11y ago
    Great. Then put those options near the top. Why are options on man pages organized alphabetically? What common use case drives that decision?
    - hk__2 11y ago
      Well, in a dictionary words are not listed at the beginning. The alphabet itself doesn’t have the most common letters at the beginning. What we should do is put the manpage examples at the beginning instead of the end.
- nalck 11y ago
  The purpose of documentation is to describe the software. It's not machismo, it's the complexity inherent in the system. The man page for tar isn't poorly written, tar has just accrued many options. Of course there may be unhelpful answers to requests for help. It may also be that industrial technology (Unix) is not as simple or easy to use as consumer technology. Tl;dr: Blame the software stack.

deleted 11y ago

[deleted]

manigandham 11y ago

How is this much different from today? plenty of people just learn what they need from Google for their use case without reading through man pages and understanding every option. If you need more than the supermarket... then learn how to fish?

beshrkayali 11y ago

That's true, but I don't think it'd be a problem since you won't be able to really understand how something works and eventually you'd not know how to use the thing. There's always a wrong way to use something. The good thing is that this is not being promoted as a replacement, but rather a helpful addition. I see it very useful as an alternative to hunting down for tutorials before you want to use some tool to figure out the details (a good example in this case would be something like lxc/lxd) or as a quick memory jogger, the examples that can be provided in a tldr man page could even have a specific context, like a cheatsheet kind of a man page.

kbart 11y ago

Continuing your tool analogy, if I used a hammer only to drive a nail, why would I need to read the whole manual of building a wooden house? Knowing your tool is important, but I find myself spending way too much time reading manpages and looking for how to accomplish a trivial task on Linux, so TLDR for most common (simple) use cases looks like a great idea.

hk__2 11y ago
Reading the manual once will save you a lot of time reading TLDR over and over. Which is not to say you won’t read it; but you’ll read it less than without reading the manual first.
- msvalkon 11y ago
  I find this hard to believe. You probably need to read the man page and perform the action over and over again. At least personally, I need to do thing X and to achieve that I know I need to use tool Y. I read the man page of Y and very satisfyingly do the thing X. A month from now I have to do something similar to X and cannot for the life of me remember what freakish incantations need to be performed in order to do the same thing so I have to go through the man page again. This is where I'd like the tl/dr of it. I don't need Y often enough to actually warrant spending much time on learning to use the niche cli it requires..
- kbart 11y ago
  I doubt that. I don't try to memorize commands (even more so - manuals), so it's more like I'm reading manual over and over again, which takes more time than reading TLDR. I agree that it's important to understand what command is used for and what capabilities it has, but trying to remember all these flags by heart is waste of limited brain resources imho.

logingone 11y ago

I was surprised the other day when I was reading something about containers, and the author explained what the touch command does.

iamtew 11y ago

Agreed, currently the pages only show quick syntax examples, would be good to have a brief description of the tool and what it does. Also perhaps have a tldr page on how to read man pages could be useful. Or this: http://www.tfug.org/helpdesk/general/man.html http://www.tfug.org/helpdesk/general/man.html

ZenoArrow 11y ago

Nobody can be an expert in every single tool they use, furthermore it's a waste of time if you have the option of learning things when the need arises. Not only would you have forgotten most of the text of man pages after reading it, you're also unlikely to ever use most of the options you found in them. The important first step in learning how to use a command line tool is to have a first working example, i.e. you've made the tool do something you wanted. From there, all you need to know is how to find out more about what it can do. Skim read through some examples, anything else you think could be useful? Try it out. The rest can be forgotten. There's no harm in keeping knowledge outside our memory if we know how to research it if needed.

lunchbox 11y ago

Yes but overall, isn't it better to at least have the choice to go to the supermarket? (As you kind of acknowledge in your own example.)

hk__2 11y ago
Yes I’m not saying you should never use tldr or similar tools; just that you could benefit from reading the manpages from time to time. I learnt more things from reading `man bash` than from any StackOverflow question or post on the Web.

nommm-nommm 11y ago

Thats like saying you dont know how to fish unless you learn the detailed operation of 10 different types of fishing boats. None of which you have access to, you're fishing from the dock and your budget is $20.

hk__2 11y ago
> Thats like saying you dont know how to fish unless you learn the detailed operation of 10 different types of fishing boats. No, that’s not like saying that. `man tar` tells you which option to use for each use case; not the detailed algorithm of each compression algorithm.

wtbob 11y ago

> It’s like learning how to fish vs. bying fish at the supermarket. And then there are the sad misguided souls using fish as their login shells (I kid, I kid…).