7 ms·

I'm not sure what the purview of the LWN documentation project is (in terms of, are those the man pages I look at when I'm using Fedora?) but I really don't lik

I'm not sure what the purview of the LWN documentation project is (in terms of, are those the man pages I look at when I'm using Fedora?) but I really don't like what has been happening to man pages. They're becoming bloated and beginner-y and not terse and dense technical descriptions of what I need to know.

arccy 2y ago
Terse was fine when you had 10 tools with 5 options each. Now we have so many more tools and each has grown a large number of flags. Nobody can remember them all so the docs need to say more. Plus the more niche flags need more explanations.
- fsckboy 2y ago
  I like the flags documentation, there are too many other words. I also used to like the examples at the bottom.
  - necovek 2y ago
    --help should give you basic docs for GNU utilities. Manpages should be more extensive (examples included). As far as GNU tools go, their attempt to move docs to (tex)info format for better interactivity has largely failed, so I guess most of that content is slowly moving over to manpages now.
    - setopt 2y ago
      > As far as GNU tools go, their attempt to move docs to (tex)info format for better interactivity has largely failed I think the only community where it kind of succeeded is the Emacs community, thanks to the built-in info reader and that a lot of Emacs docs got written in info.
  - setopt 2y ago
    If you like examples, you might like the “tldr” command. https://tldr.sh/ https://tldr.sh/
dooglius 2y ago
Can you give a before/after example of this happening? My impression has been that man pages don't change all that much aside from adding new features.
- fsckboy 2y ago
  i'll be happy to hit ^R a few times and see if it coughs up some man pages i looked at that left me disappointed... I use a number of different boxes so could take me some time to visit them all
  - Rediscover 2y ago
    Try comparing OpenBSD (or Solaris or ...) man pages to those on Linux? The one for traceroute(8) has some great commentaries on the sample output ("God only knows what's going on with 12."). It's a personal favorite.
    - petee 2y ago
      Anytime I've had an issue with an OpenBSD man page (rarely) I take 5 minutes to go play in Linux to remember just how terrible it could be I dread Linux man pages
- LtWorf 2y ago
  git diff
dannyobrien 2y ago
I think you knew this, but for clarity: the man project is being reported on by Linux Weekly News (LWN), but it's not run by them. They're just the news outlet. And an excellent one, that you should totally support and subscribe: https://lwn.net/subscribe/ https://lwn.net/subscribe/
- fsckboy 2y ago
  you're half right, i thought otherwise, but not firmly, and when i followed the link to the site and found a discussion that looked like a project discussion, it dispelled my doubt, which turns out was a righteous doubt
  - LtWorf 2y ago
    You are of course entirely wrong. I understand not knowing what lwn is… but why insist?
- rc00 2y ago
  [flagged]
  - homebrewer 2y ago
    The exact same thing can be said about "folio bias", or "bcachefs bias", or "git bias", or "RCU bias", or anything else that's really important for the development of the Linux kernel. I don't have strong opinions about Rust (either for or against it), and, having read the site since about 2016, don't see anything out of the ordinary. Its primary target audience always were Linux kernel developers, and Rust is becoming increasingly important for them whether they like it or not. Would ignoring its integration into the kernel be an example of "unbiased reporting"?
    - rc00 2y ago
      This is going to spin out but Rust is not a fit for kernel development. It is a language fueled by what feels like a perpetual hype cycle. To say that there is nothing out of the ordinary means you haven't compared the site before and after. Out of all the languages and actual things for kernel developers to become increasingly concerned with, Rust is not one of them. To ignore this practicality and suggest that having the Rust agenda carried forward is incorrect. The current experimentation with Rust will end and what will you say when that happens? Many already falsely claim the kernel ships with Rust when it does not. How does that not indicate that a bias is leading to the spread of misinformation? Why is this okay for Rust but maybe not in other areas? Would you feel the same if it were AI articles instead?
pm215 2y ago
AIUI the "Linux man-pages project" does provide the manpages you're reading, but only some of them. Specifically, its readme describes the scope as: "The manual pages in this project document primarily the Linux kernel and the GNU C library, but also consider relevant differences in other kernels or C libraries. These pages are most of the section 2, 3, 4, 5, 7 man pages for GNU/Linux. A few pages are provided in sections 1 and 8 for commands that are not documented in other packages, and there are a few pages in sections 5 and 8 for the timezone utilities." Most manpages for individual command line programs are written and shipped by the projects or authors of those programs. And if there are manpages for functions in non-libc libraries those are generally provided and shipped by the authors of those libraries. The wide range of origins for manpages means there isn't going to be a single consistent style over every manpage in a Linux system (and of course "don't ship a manpage at all" remains a popular choice).
LtWorf 2y ago
> the LWN documentation project LWN is not a documentation project. It's a news outlet.
- rc00 2y ago
  It is not a news outlet. At least, not in the general sense of what makes for a good news outlet. Good news outlets don't have bias. It is a personal blog purporting to be news at this point.
  - homebrewer 2y ago
    I would be honestly interested to learn about one or two unbiased news outlets, because I don't know any, tech news or otherwise. What is usually meant by "unbiased" is "biased in the same way as I am".
    - rc00 2y ago
      Assuming this statement was made in good faith, there are many depending on the area of focus. For general tech, there's CNET, The Verge, TechCrunch, Ars Technica, Tom's Hardware, etc. For Linux, there's Phoronix, Linuxiac, Linux Journal, DistroWatch, etc. What I mean by "unbiased" is neutral coverage on actual news, meaning just the facts. If you pay attention to the coverage at LWN, there is an inherent Rust bias that dominates regular news. Just try to go more than a few days without new articles being published with a pro-Rust stance. Actual data with stories and coverage over the years would illuminate this easily.
      - encom 2y ago
        >The Verge >unbiased
  - immibis 2y ago
    So... A news outlet.
nkrisc 2y ago
This gave me a chuckle thinking about every time a beginner was told to “read the man page” in response to a question.
- hulitu 2y ago
  There are good written man pages.

arccy 2y ago

Terse was fine when you had 10 tools with 5 options each. Now we have so many more tools and each has grown a large number of flags. Nobody can remember them all so the docs need to say more. Plus the more niche flags need more explanations.

fsckboy 2y ago
I like the flags documentation, there are too many other words. I also used to like the examples at the bottom.
- necovek 2y ago
  --help should give you basic docs for GNU utilities. Manpages should be more extensive (examples included). As far as GNU tools go, their attempt to move docs to (tex)info format for better interactivity has largely failed, so I guess most of that content is slowly moving over to manpages now.
  - setopt 2y ago
    > As far as GNU tools go, their attempt to move docs to (tex)info format for better interactivity has largely failed I think the only community where it kind of succeeded is the Emacs community, thanks to the built-in info reader and that a lot of Emacs docs got written in info.
- setopt 2y ago
  If you like examples, you might like the “tldr” command. https://tldr.sh/ https://tldr.sh/

dooglius 2y ago

Can you give a before/after example of this happening? My impression has been that man pages don't change all that much aside from adding new features.

fsckboy 2y ago
i'll be happy to hit ^R a few times and see if it coughs up some man pages i looked at that left me disappointed... I use a number of different boxes so could take me some time to visit them all
- Rediscover 2y ago
  Try comparing OpenBSD (or Solaris or ...) man pages to those on Linux? The one for traceroute(8) has some great commentaries on the sample output ("God only knows what's going on with 12."). It's a personal favorite.
  - petee 2y ago
    Anytime I've had an issue with an OpenBSD man page (rarely) I take 5 minutes to go play in Linux to remember just how terrible it could be I dread Linux man pages
LtWorf 2y ago
git diff

dannyobrien 2y ago

I think you knew this, but for clarity: the man project is being reported on by Linux Weekly News (LWN), but it's not run by them. They're just the news outlet. And an excellent one, that you should totally support and subscribe: https://lwn.net/subscribe/ https://lwn.net/subscribe/

fsckboy 2y ago
you're half right, i thought otherwise, but not firmly, and when i followed the link to the site and found a discussion that looked like a project discussion, it dispelled my doubt, which turns out was a righteous doubt
- LtWorf 2y ago
  You are of course entirely wrong. I understand not knowing what lwn is… but why insist?
rc00 2y ago
[flagged]
- homebrewer 2y ago
  The exact same thing can be said about "folio bias", or "bcachefs bias", or "git bias", or "RCU bias", or anything else that's really important for the development of the Linux kernel. I don't have strong opinions about Rust (either for or against it), and, having read the site since about 2016, don't see anything out of the ordinary. Its primary target audience always were Linux kernel developers, and Rust is becoming increasingly important for them whether they like it or not. Would ignoring its integration into the kernel be an example of "unbiased reporting"?
  - rc00 2y ago
    This is going to spin out but Rust is not a fit for kernel development. It is a language fueled by what feels like a perpetual hype cycle. To say that there is nothing out of the ordinary means you haven't compared the site before and after. Out of all the languages and actual things for kernel developers to become increasingly concerned with, Rust is not one of them. To ignore this practicality and suggest that having the Rust agenda carried forward is incorrect. The current experimentation with Rust will end and what will you say when that happens? Many already falsely claim the kernel ships with Rust when it does not. How does that not indicate that a bias is leading to the spread of misinformation? Why is this okay for Rust but maybe not in other areas? Would you feel the same if it were AI articles instead?

pm215 2y ago

AIUI the "Linux man-pages project" does provide the manpages you're reading, but only some of them. Specifically, its readme describes the scope as: "The manual pages in this project document primarily the Linux kernel and the GNU C library, but also consider relevant differences in other kernels or C libraries. These pages are most of the section 2, 3, 4, 5, 7 man pages for GNU/Linux. A few pages are provided in sections 1 and 8 for commands that are not documented in other packages, and there are a few pages in sections 5 and 8 for the timezone utilities." Most manpages for individual command line programs are written and shipped by the projects or authors of those programs. And if there are manpages for functions in non-libc libraries those are generally provided and shipped by the authors of those libraries. The wide range of origins for manpages means there isn't going to be a single consistent style over every manpage in a Linux system (and of course "don't ship a manpage at all" remains a popular choice).

LtWorf 2y ago

> the LWN documentation project LWN is not a documentation project. It's a news outlet.

rc00 2y ago
It is not a news outlet. At least, not in the general sense of what makes for a good news outlet. Good news outlets don't have bias. It is a personal blog purporting to be news at this point.
- homebrewer 2y ago
  I would be honestly interested to learn about one or two unbiased news outlets, because I don't know any, tech news or otherwise. What is usually meant by "unbiased" is "biased in the same way as I am".
  - rc00 2y ago
    Assuming this statement was made in good faith, there are many depending on the area of focus. For general tech, there's CNET, The Verge, TechCrunch, Ars Technica, Tom's Hardware, etc. For Linux, there's Phoronix, Linuxiac, Linux Journal, DistroWatch, etc. What I mean by "unbiased" is neutral coverage on actual news, meaning just the facts. If you pay attention to the coverage at LWN, there is an inherent Rust bias that dominates regular news. Just try to go more than a few days without new articles being published with a pro-Rust stance. Actual data with stories and coverage over the years would illuminate this easily.
    - encom 2y ago
      >The Verge >unbiased
- immibis 2y ago
  So... A news outlet.

nkrisc 2y ago

This gave me a chuckle thinking about every time a beginner was told to “read the man page” in response to a question.

hulitu 2y ago
There are good written man pages.