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

81–90 of 179 posts

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

#81

Post by Brave-Steak »

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.

Yeah, no. The use cases for man and tldr are completely different, and trying to convince every single project to make their man pages more friendly to people who just want to get their work done is just ... well, an impossible amount of effort. tldr coalesces a community around a common goal, and they can work towards that goal without fighting hundreds of different maintainers on making man pages more accessible.

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

#82

Post by munk-a »

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.

I dunno, the TLDR page highlighted tar which seems a bit odd since tar has always gone out of its way to have a very strong and useful manpage - specifically having several examples[1] at the top of the page before diving into all the intricacies of the arguments.

1. Including tar -cf and tar -xf probably the two you want to run in most cases. See: https://linux.die.net/man/1/tar

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

#83

Post by joshklein »

diebeforei485 wrote: post #80
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.

No, they serve two different purposes. Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept. This is something different. It's a tutorial of how to do the most common things using that tool. It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples? Unless you've read formal specs for ot…

> they serve two different purposes

I agree, but I'm also painfully aware of man page incompleteness every time I'm on a non-OpenBSD system. I'd be grateful to anyone who chipped away at proper tagging for any GNU software. One should be able to :t to jump to the reference for any flag.

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

#84

Post by toomim »

ausjke wrote: post #44
ausjke wrote: post #30

Earlier quoted context omitted.

amazing, just tested it out, i hope it can add devdocs.io support, and update vim plugin to newer ones. this will likely replace my tldr soon

I have yet to see node.js API support from any REPL or shell or vim or tldr, the only option is access it from browser, which is not enough. https://zealdocs.org is another great source, similar to https://devdocs.io

Grandparent just showed how to use it on the command-line, with curl.

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

#86

Post by Scarblac »

diebeforei485 wrote: post #80
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.

No, they serve two different purposes. Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept. This is something different. It's a tutorial of how to do the most common things using that tool. It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples? Unless you've read formal specs for ot…

It would be quite nice to have that quick tutorial in a new section at the top of man pages, in addition to what's already there.

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

#88

Post by [deleted] »

diebeforei485 wrote: post #80
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.

No, they serve two different purposes. Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept. This is something different. It's a tutorial of how to do the most common things using that tool. It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples? Unless you've read formal specs for ot…

[deleted]

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

#89

Post by overcast »

Darkphibre wrote: post #75
overcast wrote: post #70

Earlier quoted context omitted.

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.

Back in 2000-2005 I worked on the SQL Server documentation. If I remember correctly, when we instrumented the docs we found that the VAST majority of users skipped over all the descriptions and parameter definitions, and jumped straight to the examples of usage. Turns out observation is the fastest way to learn/remember. We redoubled our efforts to include examples of more obscure usage patterns, rather than relying…

That's EXACTLY what I do. I imagine there are some that are great at reading white papers, but I am not one of them, and I'm not alone. Experience > Education.

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

#90

Post by smhenderson »

topspin wrote: post #76
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.

> The maintainers would be thrilled to have them. Would they? The tldr.sh site prominently offers a sample of usage examples for a command; tar specifically. If one checks the tar man page there are no examples. This is policy, apparently promulgated by GNU et al. in favor of "info". I haven't the time right now to hunt down the official position, but here[1] is a SO discussion. Should this TLDR thing correct that lo…

I'm aware of GBU's preference for info but systems vary. Just to use your example, I'm typing this on Slackware and when I pull up man tar there are three examples, right after Synopsis and Description. Examples for extracting, both gzipped and regular archives, and creating a tar file are given.

And when I shell into an OpenBSD server their man page for tar has several examples at the bottom of the page.

Man, IMO, is a lot like Linux distros in that they are not all created equal, pull from a lot of different sources and can be inconsistent if you're not looking at the correct ones for whatever system you are on.

I too think TLDR is a good idea but that's no reason not to encourage that some of their work be ported back to man pages in their examples' sections.

Post reply on HN