Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

TLDR pages: Simplified, community-driven man pages

tldr.sh

Post reply on HN
Print view View original

21–30 of 179 posts

Re: TLDR pages: Simplified, community-driven man pages

#21

Post by lordgrenville »

CaptArmchair wrote: post #19
stared wrote: post #12

I would be happy to see such a thing taking off. Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain all information, but a clear F on UX. Some packages get slightly better with starting from the most common use cases, with examples (and digestible errors). However, I would be even more interested to see what is the actual usage pattern (e.g. from .bash_histor…

Man pages are intended to be an exhaustive description of the individual options, switches and command arguments and what they do; but they won't tell you how to combine those to be useful in your particular case. It's up to you to figure that out. tldr caters to an entirely different heuristic: I have this use case, give me a list of use cases and the corresponding combination of switches, options and arguments for…

I frequently use TLDR, and I wouldn't describe it as an incantation. It's for the case where, say, I know there's a grep flag for inverse match or case-insensitive, but don't use it often enough to remember it. It surfaces the (community-driven) top use cases, and it's pretty clear from the context what the flags are doing. (As seen here: https://github.com/tldr-pages/tldr/blob/master/pages/common/... ) If I don't see my use-case in tldr I'll move on to the man page.

OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :)

Re: TLDR pages: Simplified, community-driven man pages

#23

Post by reaperducer »

stared wrote: post #12

I would be happy to see such a thing taking off. Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain all information, but a clear F on UX. Some packages get slightly better with starting from the most common use cases, with examples (and digestible errors). However, I would be even more interested to see what is the actual usage pattern (e.g. from .bash_histor…

It may contain all information, but a clear F on UX.

What I find annoying is the number of command line programs that don't even have man pages anymore. Or maybe that's just an artifact of installing them with brew?

What I find interesting is that for the most part (there are exceptions), the older the man page, the more useful it is. Realistic examples. Succinct descriptions. User-friendly terminology. Too many of the newer man pages seem inflated and full of jargon to make themselves seem important or worthy.

Re: TLDR pages: Simplified, community-driven man pages

#25

Post by lynndotpy »

stared wrote: post #12

I would be happy to see such a thing taking off. Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain all information, but a clear F on UX. Some packages get slightly better with starting from the most common use cases, with examples (and digestible errors). However, I would be even more interested to see what is the actual usage pattern (e.g. from .bash_histor…

I'm also interested in a `.bash_history` kind of dataset. If you become aware of this, I'd love to see such a thing.

Re: TLDR pages: Simplified, community-driven man pages

#26

Post by CaptArmchair »

lordgrenville wrote: post #21
CaptArmchair wrote: post #19

Earlier quoted context omitted.

Man pages are intended to be an exhaustive description of the individual options, switches and command arguments and what they do; but they won't tell you how to combine those to be useful in your particular case. It's up to you to figure that out. tldr caters to an entirely different heuristic: I have this use case, give me a list of use cases and the corresponding combination of switches, options and arguments for…

I frequently use TLDR, and I wouldn't describe it as an incantation. It's for the case where, say, I know there's a grep flag for inverse match or case-insensitive, but don't use it often enough to remember it. It surfaces the (community-driven) top use cases, and it's pretty clear from the context what the flags are doing. (As seen here: https://github.com/tldr-pages/tldr/blob/master/pages/common/... ) If I don't se…

> it's pretty clear from the context

I think that largely depends on who's using the tools and how acquainted they are with command line tools. An absolute beginner likely will not know what tar's 'f' flag does, or assume something else.

> OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :)

And I absolutely have no qualms doing the same when push comes to shove. Ain't nobody always got the time. ;-)

Re: TLDR pages: Simplified, community-driven man pages

#28

Post by wongarsu »

reaperducer wrote: post #23
stared wrote: post #12

I would be happy to see such a thing taking off. Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain all information, but a clear F on UX. Some packages get slightly better with starting from the most common use cases, with examples (and digestible errors). However, I would be even more interested to see what is the actual usage pattern (e.g. from .bash_histor…

It may contain all information, but a clear F on UX. What I find annoying is the number of command line programs that don't even have man pages anymore. Or maybe that's just an artifact of installing them with brew? What I find interesting is that for the most part (there are exceptions), the older the man page, the more useful it is. Realistic examples. Succinct descriptions. User-friendly terminology. Too many of t…

I don't think I've encountered anything on Ubuntu that doesn't have a man page, but it also seems like many of the man pages are created or improved by Debian or Ubuntu/Canonical. Homebrew probably wouldn't have those.
Post reply on HN