News for hackers. Stuff that matters.
Re:TLDR pages by hk__2 on Monday December 28, 2015 @07:19AM (#10800790)
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.
Re:TLDR pages by coldtea on Monday December 28, 2015 @07:32AM (#10800842)
>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?

Re:TLDR pages by jordanpg on Monday December 28, 2015 @08:04AM (#10800937)
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!

Re:TLDR pages by hk__2 on Monday December 28, 2015 @10:56AM (#10801663)
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).

Re:TLDR pages by ryandrake on Monday December 28, 2015 @12:35PM (#10802222)
Great. Then put those options near the top. Why are options on man pages organized alphabetically? What common use case drives that decision?
Re:TLDR pages by hk__2 on Monday December 28, 2015 @02:10PM (#10802742)
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.
Re:TLDR pages by nalck on Monday December 28, 2015 @11:28AM (#10801870)
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.

Re:TLDR pages by moron4hire on Monday December 28, 2015 @10:34AM (#10801535)
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.

Re:TLDR pages by kbart on Monday December 28, 2015 @07:58AM (#10800912)
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.
Re:TLDR pages by hk__2 on Monday December 28, 2015 @10:58AM (#10801683)
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.
Re:TLDR pages by msvalkon on Monday December 28, 2015 @11:11AM (#10801775)
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..

Re:TLDR pages by kbart on Tuesday December 29, 2015 @01:43AM (#10805591)
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.
Re:TLDR pages by ZenoArrow on Monday December 28, 2015 @08:03AM (#10800935)
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.

Re:TLDR pages by manigandham on Monday December 28, 2015 @07:49AM (#10800876)
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?

Re:TLDR pages by beshrkayali on Monday December 28, 2015 @07:57AM (#10800911)
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.

Re:TLDR pages by nommm-nommm on Monday December 28, 2015 @09:03AM (#10801084)
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.
Re:TLDR pages by hk__2 on Monday December 28, 2015 @10:46AM (#10801604)
> 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.

Re:TLDR pages by lunchbox on Monday December 28, 2015 @08:04AM (#10800938)
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.)
Re:TLDR pages by hk__2 on Monday December 28, 2015 @10:39AM (#10801557)
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.
Re:TLDR pages by iamtew on Monday December 28, 2015 @08:02AM (#10800931)
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

Re:TLDR pages by wtbob on Monday December 28, 2015 @09:39AM (#10801234)
> 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…).

Re:TLDR pages by logingone on Monday December 28, 2015 @07:58AM (#10800913)
I was surprised the other day when I was reading something about containers, and the author explained what the touch command does.
Re:TLDR pages by gexos on Monday December 28, 2015 @07:28AM (#10800824)
"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.