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

171–179 of 179 posts

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

#171

Post by TheKarateKid »

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.

Given the general attitude of the GNU/Linux community, I could see most examples/edits being rejected with elitists saying "RTFM!"

Remember, these are the same people that claim the Emacs and Vim are better to code in, and that IDEs are for inexperienced/lazy coders.

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

#172

Post by musicale »

I learned BSD largely from the man pages, but man pages on Linux distributions always felt a bit deficient to me, partly because of GNU utilities with placeholder man pages that just said "use info instead" and partly because of (at the time at least) many missing EXAMPLES sections.

I think they've improved greatly, but man pages on Debian, Ubuntu et al. still feel a bit like second-class citizens.

What TLDR pages seem to be getting right is putting EXAMPLES first or second rather than last, and/or having a command to bring up EXAMPLES.

Also I want to put in a plug for AUTHORS/HISTORY and BUGS sections. The former can create a sense of community and context and the latter can point out annoying gotchas.

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

#173

Post by Semiapies »

tyrust wrote: post #51
Semiapies wrote: post #36

Earlier quoted context omitted.

How is this "rapidly decaying third-party documentation" in any way that man isn't?

man pages are first-party, are they not?

Documentation by the makers of a program would be first-party.

Something definitely can't be both first-party and community.

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

#174

Post by chousuke »

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…

This is sadly the case with lots of Linux tools, but it's not really man's fault. Next time you need help with a UNIX tool, try reading the OpenBSD man page instead and see how it compares.

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

#175

Post by iudqnolq »

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…

> 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.

No, thankfully.

Try `man man | col -b | grep EXAMPLES`

(As an example, grep was finding EX but not EXA. Man told me I could pipe to col -b to strip formatting, hinting the issue might be special characters. This was quite helpful of them, even if it isn't strictly "man's responsibility".

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

#177

Post by JdeBP »

musicale wrote: post #172

I learned BSD largely from the man pages, but man pages on Linux distributions always felt a bit deficient to me, partly because of GNU utilities with placeholder man pages that just said "use info instead" and partly because of (at the time at least) many missing EXAMPLES sections. I think they've improved greatly, but man pages on Debian, Ubuntu et al. still feel a bit like second-class citizens. What TLDR pages se…

Context, definitely. I have myself found them to be very useful. This is why I added HISTORY sections to the user manuals for some of Daniel J. Bernstein's tools when I converted them.

* http://cr.yp.to/daemontools/multilog.html

* http://jdebp.uk./Softwares/djbwares/guide/commands/multilog....

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

#178

Post by JdeBP »

tingletech wrote: post #156
downerending wrote: post #48

Earlier quoted context omitted.

It's true that the man pages aren't meant to be the primary method of learning Unix. But they are indeed a spectacular and irreplaceable resource. One of the best things that ever happened in my career was having a desk across from the entire SunOS manual set. I'd pull them down one at a time and read them, cover to cover. It paid off, big time, and I strongly recommend it.

I was a bio major who would hang out in rooms with terminals in the early 90s. One day I saw “type ‘man man’” and “apropos” written on a chalk board. That is how I learned Unix.

Interestingly, actual bona fide AT&T System 5 Release 3 Unix had a "help" command, which was a full-screen menu-driven interactive help system.

* https://unix.stackexchange.com/a/448799/5132

There was also "learn", in BSD as I recall.

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

#179

Post by JdeBP »

killjoywashere wrote: post #142
neckardt wrote: post #136

Earlier quoted context omitted.

Ideally I would like to see an additional section in man pages devoted to examples. The TLDR pages could then be moved into the man pages.

tldr didn't choose tar as their front-page demo by accident. The tar manpage is a classic example of the CLI gods apparently going to some effort to design the Examples section to effectively tell new users to bugger the hell off.

Only to people who erroneously think that there is such a thing as "the" tar manpage. (-:

* https://news.ycombinator.com/item?id=22122279

Post reply on HN