News for hackers. Stuff that matters.
Re:TLDR pages: Simplified, community-driven man pages by overcast on Wednesday January 22, 2020 @11:40AM (#22119061)
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.
Re:TLDR pages: Simplified, community-driven man pages by JoshTriplett on Wednesday January 22, 2020 @12:23PM (#22119671)
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.
Re:TLDR pages: Simplified, community-driven man pages by overcast on Wednesday January 22, 2020 @12:28PM (#22119747)
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.
Re:TLDR pages: Simplified, community-driven man pages by JoshTriplett on Wednesday January 22, 2020 @01:10PM (#22120226)
> I'm not sure what this has to do with Kerrisk

Because the man-pages project that he maintains provides the largest set of third-party manpages (outside the project trees themselves). The majority of manpages live either in the project they document or in the man-pages project.

> I don't know why this has to be met with so much friction.

The point of this thread is that it will often not be met with friction. Examples should be in a combination of the summary and examples sections of the manpages. (Distinct modes of operation belong in the summary, more fine-grained examples go in the examples section.

Re:TLDR pages: Simplified, community-driven man pages by tylerchilds on Wednesday January 22, 2020 @12:42PM (#22119923)
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 by overcast on Wednesday January 22, 2020 @12:51PM (#22120024)
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.
Re:TLDR pages: Simplified, community-driven man pages by Darkphibre on Wednesday January 22, 2020 @01:12PM (#22120239)
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 on wordy explanations.

Re:TLDR pages: Simplified, community-driven man pages by overcast on Wednesday January 22, 2020 @01:55PM (#22120728)
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 by Polylactic_acid on Wednesday January 22, 2020 @09:18PM (#22124235)
You don't need to know what other people don't know. Just provide a copy/paste of the most common use cases and a line explaining what they do.
Re:TLDR pages: Simplified, community-driven man pages by usrusr on Wednesday January 22, 2020 @02:02PM (#22120790)
> 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 by jeltz on Wednesday January 22, 2020 @12:36PM (#22119851)
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 by b5n on Wednesday January 22, 2020 @01:05PM (#22120185)
I use manpages frequently, seems easier to learn how to read manpages than create a new project dedicated to adding examples to manpages. I find them incredibly user friendly, but I cared enough to learn how to use them.
Re:TLDR pages: Simplified, community-driven man pages by fluidcruft on Wednesday January 22, 2020 @12:18PM (#22119603)
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 entry is much lower with some simple markdown thing. Hell, I was thinking about how to abuse this thing to make my own notes about commands.

Re:TLDR pages: Simplified, community-driven man pages by aktau on Wednesday January 22, 2020 @02:38PM (#22121179)
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 by vmchale on Wednesday January 22, 2020 @11:56AM (#22119290)
On Linux that has been my experience. man pages on Mac are a little better, I've heard the BSDs do better as well.
Re:TLDR pages: Simplified, community-driven man pages by spenczar5 on Wednesday January 22, 2020 @12:06PM (#22119427)
Do you have examples of that refusal? I'm unfamiliar.
Re:TLDR pages: Simplified, community-driven man pages by edw on Wednesday January 22, 2020 @12:28PM (#22119754)
Based on my experience, the problem may be that man pages are often not where one learns how to use a tool. I still remember from long, long ago when I told a greybeard that I was trying to learn sed by reading the man page. He replied, "God help you," and guffawed.

While some man pages have examples, I don't know if man page writers see their job as teaching readers how to use a utility. The goal of man pages more often seems to be _reminding_ a person already familiar with the tool how to use a tool.

I'm, umm, _reminded_ of project READMEs. I've come to assume that when I go to a project on GitHub, I'm going to get everything I need (or pointers to everything I need) to get started with a project, but often there's a project web site that is intended to serve that purpose. I just ran into this yesterday with Falcor.

Not all man pages are like this obviously. Specifically, the section three man pages on C functions do a good job fully documenting functions.

Re:TLDR pages: Simplified, community-driven man pages by kbenson on Wednesday January 22, 2020 @02:52PM (#22121313)
The more complex a tool, the less likely a man page is going to be a good way to distill and impart the information of how to use it. Bash's mane page is so large I can almost never find what I'm looking for.

At the same time, that means a TL;DR type page is also likely to be useless. For the vast majority of software run from a shell, a man page is sufficient, and examples can be (and often are) added to good effect.

I will note that some projects split very large man pages into sub-pages, and that can work well. For example, ip, and much of the man pages on BSDs that explain how different technologies are implemented (for example, follow the references in the man page for ifconfig on OpenBSD).

Re:TLDR pages: Simplified, community-driven man pages by overcast on Wednesday January 22, 2020 @12:29PM (#22119761)
By virtue of the fact that TLDR and bropages exist? People are creating 3rd party solutions, because no one does anything with man pages.
Re:TLDR pages: Simplified, community-driven man pages by munk-a on Wednesday January 22, 2020 @01:27PM (#22120432)
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 by Jaepa on Wednesday January 22, 2020 @11:44PM (#22124936)
I'd guess this is a xkcd reference.

https://www.xkcd.com/1168/