5 ms·

Man pages are a community project. Send patches!

oblio 8y ago
While this is laudable, how many GNU projects, especially, don't use an archaic development/contribution process? I don't want to have to register on a mailing list and prepare patches. This is an honest question. Friction and barriers to entry reduce contributions.
- S-E-P 8y ago
  I second this, there's so much wasted work, and because that old contribution process there's no guarantee that even an absolutely fantastic patch, like a better man page for example. Will ever see the light of day. I've tried in the past, it doesn't work out (not man pages, but I was fixing a bug and yeah, three, four submissions was enough for me to quit trying)
- jwilk 8y ago
  More importantly, many (most?) GNU projects don't care about man pages: https://www.gnu.org/prep/standards/html_node/Man-Pages.html https://www.gnu.org/prep/standards/html_node/Man-Pages.html
  - jplayer01 8y ago
    This encapsulates one of my biggest gripes with Linux. A lack of appreciation for adequate/good documentation. > The time you spend on the man page is time taken away from more useful work. Making sure your users know how your program works, how to use it and what it's capable of seems incredibly important and useful to me. If it weren't for Arch Linux's fantastic focus on documenting everything to do with Linux, I wouldn't be using Linux at all.
    - owaty 8y ago
      That page is specific to man pages, not to documentation in general. See https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm...
    - KC8ZKF 8y ago
      GNU deprecates man pages in favor of texinfo, not no documentation at all. https://www.gnu.org/prep/standards/html_node/Documentation.html#Documentation https://www.gnu.org/prep/standards/html_node/Documentation.h...
- Sir_Cmpwn 8y ago
  It's not hard, just suck it up and register for the ML, and prepare the patches. People are irrationally scared of this process. There are plentiful guides.
  - mdaniel 8y ago
    It's not always that it's hard, rather it can be demoralizing to have the same experience that @S-E-P did [a sibling comment to yours] where you _do_ expend the energy and then patches sit unactioned for months or years
    - Sir_Cmpwn 8y ago
      Your patches are your responsibility. Bump them, reach out to maintainers directly, etc. Manual improvements are easy to review once you can get someone to.
      - oblio 8y ago
        Or I could just do what 99% of devs do, not give a crap and try StackOverflow/blogs to find an answer... That was my whole point, higher friction => much fewer contributions.
        Sir_Cmpwn 8y ago
        Higher friction => higher quality contributions.
        aktau 8y ago
        But also fewer contributions, I reckon. If someone wants to contribute something big, they'll jump through all the hoops. But if all one wants is to contribute another example to a man page, I'd wager they're more easily discouraged by an arcane setup process. GitHub solves a lot of this friction by having: 1. One account for manifesting your chosen identity, which you likely already have. 2. One common way of getting the source code and sending diffs/patches (read: PRs). The workflow is quite similar, in the abstract. But GitHub and friends solve important pain points.

While this is laudable, how many GNU projects, especially, don't use an archaic development/contribution process? I don't want to have to register on a mailing list and prepare patches. This is an honest question. Friction and barriers to entry reduce contributions.

S-E-P 8y ago
I second this, there's so much wasted work, and because that old contribution process there's no guarantee that even an absolutely fantastic patch, like a better man page for example. Will ever see the light of day. I've tried in the past, it doesn't work out (not man pages, but I was fixing a bug and yeah, three, four submissions was enough for me to quit trying)
jwilk 8y ago
More importantly, many (most?) GNU projects don't care about man pages: https://www.gnu.org/prep/standards/html_node/Man-Pages.html https://www.gnu.org/prep/standards/html_node/Man-Pages.html
- jplayer01 8y ago
  This encapsulates one of my biggest gripes with Linux. A lack of appreciation for adequate/good documentation. > The time you spend on the man page is time taken away from more useful work. Making sure your users know how your program works, how to use it and what it's capable of seems incredibly important and useful to me. If it weren't for Arch Linux's fantastic focus on documenting everything to do with Linux, I wouldn't be using Linux at all.
  - owaty 8y ago
    That page is specific to man pages, not to documentation in general. See https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm...
  - KC8ZKF 8y ago
    GNU deprecates man pages in favor of texinfo, not no documentation at all. https://www.gnu.org/prep/standards/html_node/Documentation.html#Documentation https://www.gnu.org/prep/standards/html_node/Documentation.h...
Sir_Cmpwn 8y ago
It's not hard, just suck it up and register for the ML, and prepare the patches. People are irrationally scared of this process. There are plentiful guides.
- mdaniel 8y ago
  It's not always that it's hard, rather it can be demoralizing to have the same experience that @S-E-P did [a sibling comment to yours] where you _do_ expend the energy and then patches sit unactioned for months or years
  - Sir_Cmpwn 8y ago
    Your patches are your responsibility. Bump them, reach out to maintainers directly, etc. Manual improvements are easy to review once you can get someone to.
    - oblio 8y ago
      Or I could just do what 99% of devs do, not give a crap and try StackOverflow/blogs to find an answer... That was my whole point, higher friction => much fewer contributions.
      - Sir_Cmpwn 8y ago
        Higher friction => higher quality contributions.
        aktau 8y ago
        But also fewer contributions, I reckon. If someone wants to contribute something big, they'll jump through all the hoops. But if all one wants is to contribute another example to a man page, I'd wager they're more easily discouraged by an arcane setup process. GitHub solves a lot of this friction by having: 1. One account for manifesting your chosen identity, which you likely already have. 2. One common way of getting the source code and sending diffs/patches (read: PRs). The workflow is quite similar, in the abstract. But GitHub and friends solve important pain points.