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

61–70 of 179 posts

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

#61

Post by thrwaway69 »

CaptArmchair wrote: post #26
lordgrenville wrote: post #21

Earlier quoted context omitted.

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…

I will bite - I have been using linux for 4 years. I have used tar a lot and I don't know what v means. I switch between -xvf, -xvz, etc.

x - extract | f - file | z - operating on tar.gz or similar.

Edit: v - verbose

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

#62

Post by josephernest »

1) Great project!

Is there a simple way to install it without having to install Node.js or Haskell or Ruby? (I don't want to install Node.js just for it)

Is there a

    apt-get install tldr
solution on recent Debian / Ubuntu distros without installing another additional package manager?

I mean even the bash solution:

    bpkg ...
does not work out of the box.

(bpkg or brew or npm aren't installed by default)

2) Is TLDR linked with the project cht.sh? e.g curl cht.sh/tar? Does it share a common source of documentation are they two totally different projects?

3) Few people won't remember tldr.ostera.io (I won't)... Ok we have bookmarks, but still, it would be more convenient if we could just do:

    tldr.sh/tar
    tldr.sh/git_push
instead of having to remember ostera.tldr.io oh no ostera.tldr.sh oh no tldr.ostera.sh no...

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

#63

Post by jeltz »

overcast wrote: post #34
ddevault wrote: post #27

A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.

It seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.

Doesn't each project maintain its own man pages? There is a huge variation in quality between them with some being excellent while others are lacking.

Have you tried talking to any of the projects?

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

#64

Post by zantana »

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…

That doesn't preclude them from including examples of the most commonly used flags and scenarios.

Man pages for newer tools, like all of the lvm utilities, include examples at the end.

I would like to see it similar to what powershell has with their examples built into the documentation.

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

#65

Post by nebulous1 »

ddevault wrote: post #27

A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.

Ideally this information would be controlled by the individual package maintainers, I agree.

However, realistically at the moment I don't see man pages competing with the spirit of tldr/bro/whatever, and I suspect that PRs geared towards making them compete would in fact be rejected by most projects.

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

#66

Post by [deleted] »

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…

[deleted]

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

#67

Post by jlg23 »

ddevault wrote: post #27

A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.

Yes. The given example shows exactly what I would expect in the EXAMPLES section of a man page anyways. If not, it's worth a patch.

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

#68

Post by tylerchilds »

overcast wrote: post #58
JoshTriplett wrote: post #57

Earlier quoted context omitted.

The maintainer of the manpages project, Michael Kerrisk, is quite responsive and interested in improvements. I've generally found the maintainers of other software to be receptive to documentation patches, as well.

I'm not sure what this has to do with Kerrisk. Software maintainers just need to simply add examples of using the software they use. They know best how it works, I don't know why this has to be met with so much friction. Like not posting images of your new game/image library. People want examples of stuff.

I think the hardest part is that people don't know what others don't know. When you're so close to a project, things that are obvious to you are impossible to new people, but you don't realize how impossible it is until you get that feedback.

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

#70

Post by overcast »

tylerchilds wrote: post #68
overcast wrote: post #58

Earlier quoted context omitted.

I'm not sure what this has to do with Kerrisk. Software maintainers just need to simply add examples of using the software they use. They know best how it works, I don't know why this has to be met with so much friction. Like not posting images of your new game/image library. People want examples of stuff.

I think the hardest part is that people don't know what others don't know. When you're so close to a project, things that are obvious to you are impossible to new people, but you don't realize how impossible it is until you get that feedback.

Just start with the assumption that no one understands how to read a man page and how to translate that into a full command line operation. A simple example goes A LONG WAY.
Post reply on HN