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

91–100 of 179 posts

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

#91

Post by usrusr »

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.

> They know best how it works

But they don't necessarily know best what usage patterns work well for people who are not maintainer-level experts.

I see a strong case for having separate texts for documenting the interface (striving for completeness and low redundancy) and introductory teaching. I don't think that I'd like seeing each man page prepended with a wordy ELIF and two pages of trivial examples. And I'm not saying this because I'd not need the ELIF, quite the opposite, I just don't think that it would be wise to mix them.

Having them maintained in one place, passed through the same distribution channels and available on the command line, now that would great of course. The minimum almost-requirement for a crowdsourcing effort for that content could be a contribution licence that is 100% compatible with the real thing, not 99%, not 99.99. Just in case.

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

#92

Post by SaulOfTheJungle »

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…

> No, they serve two different purposes.

I don't see why they could not serve both purposes.

Man pages should start with a tldr section followed by the full reference/spec.

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

#93

Post by SnowflakeOnIce »

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…

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

A messed-up MANPATH environment variable can also cause man pages to not be found. In ‘man’ used on many flavors of Linux, MANPATH behaves differently from, say, PATH: an empty colon-delimited section means something like “use the system’s regular ‘man’ configuration for finding man pages”. Without that, it seems like a bad MANPATH setting will cause default mannpages not to be found.

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

#94

Post by fhennig »

SaulOfTheJungle wrote: post #92
diebeforei485 wrote: post #80

Earlier quoted context omitted.

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…

> No, they serve two different purposes. I don't see why they could not serve both purposes. Man pages should start with a tldr section followed by the full reference/spec.

Yes, put both things in the man page!

Looking at some examples of tldrs, it mostly boils down to the most common use cases as examples. So well written man pages already have an "examples" section, and that really helps!

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

#95

Post by topspin »

smhenderson wrote: post #90
topspin wrote: post #76

Earlier quoted context omitted.

> 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, i…

A quick survey of GNU tar man pages, by program version and the date that appears in the page itself:

   1.23 March, 2012:    no examples (RHEL 6)
   1.26 March, 2015:    no examples (OpenSUSE 13.1)
   1.26 February, 2016: no examples (CentOS 7)
   1.29 March, 2016:    limited examples (Ubuntu 1804)
The last has no actual "EXAMPLES" section in the man page; only some incidental examples appearing among a discussion of "Option styles." I suspect this is also what you see; it's in the same position in the page. So there is some evidence that examples aren't entirely prohibited in GNU man pages, at least in recent years. Progress, I guess. The latest work on this man page (release 1.32) shows no further progress.

TLDR goes well beyond those incidental examples and is far closer to what I'd hope to see; first class, worked example forms eagerly supplied. Without suffering info.

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

#97

Post by xorcist »

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…

There's no reason man pages can't be both.

Many man pages contain examples and common usages. See for example the rsync man page, with complete examples of how to backup common file systems.

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

#98

Post by aktau »

fluidcruft wrote: post #52
overcast wrote: post #34

Earlier quoted context omitted.

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 GNU still scoff at man pages and foist texinfo? Honestly who wants to waste their time with roff etc? The focus has been making it easier for the developers to write literally anything. One thing uses sphynx another uses man another uses doxygen or what the hell ever. Users aren't developers. This is why everyone ends up on google and ends up on stackoverflow or random blog or watching youtube. The barrier to…

I maintain my man pages in markdown format, and convert them to roff at build time. There are plenty of tools that can do that: pandoc(1), ronn(1), ...

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

#99

Post by [deleted] »

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…

[deleted]
Post reply on HN