4 ms·

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 frie

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.

vmchale 7y ago
On Linux that has been my experience. man pages on Mac are a little better, I've heard the BSDs do better as well.
spenczar5 7y ago
Do you have examples of that refusal? I'm unfamiliar.
- edw 7y ago
  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.
  - kbenson 7y ago
    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).
- overcast 7y ago
  By virtue of the fact that TLDR and bropages exist? People are creating 3rd party solutions, because no one does anything with man pages.
fluidcruft 7y ago
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.
- aktau 7y ago
  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), ...
JoshTriplett 7y ago
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.
- overcast 7y ago
  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.
  - tylerchilds 7y ago
    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.
    - overcast 7y ago
      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.
      - Darkphibre 7y ago
        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.
        7y ago
jeltz 7y ago
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?
b5n 7y ago
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.
munk-a 7y ago
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 https://linux.die.net/man/1/tar
- Jaepa 7y ago
  I'd guess this is a xkcd reference. https://www.xkcd.com/1168/ https://www.xkcd.com/1168/

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.

vmchale 7y ago

On Linux that has been my experience. man pages on Mac are a little better, I've heard the BSDs do better as well.

spenczar5 7y ago

Do you have examples of that refusal? I'm unfamiliar.

edw 7y ago
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.
- kbenson 7y ago
  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).
overcast 7y ago
By virtue of the fact that TLDR and bropages exist? People are creating 3rd party solutions, because no one does anything with man pages.

fluidcruft 7y ago

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.

aktau 7y ago
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), ...

JoshTriplett 7y ago

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.

overcast 7y ago
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.
- tylerchilds 7y ago
  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.
  - overcast 7y ago
    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.
    - Darkphibre 7y ago
      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.
      - 7y ago

jeltz 7y ago

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?

b5n 7y ago

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.

munk-a 7y ago

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 https://linux.die.net/man/1/tar

Jaepa 7y ago
I'd guess this is a xkcd reference. https://www.xkcd.com/1168/ https://www.xkcd.com/1168/