News for hackers. Stuff that matters.
Re:Um – Create your own man pages so you can remember how to... by ddevault on Monday August 20, 2018 @07:54AM (#17799205)
Man pages are a community project. Send patches!
Re:Um – Create your own man pages so you can remember how to... by oblio on Monday August 20, 2018 @10:07AM (#17799967)
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.

Re:Um – Create your own man pages so you can remember how to... by jwilk on Monday August 20, 2018 @10:57AM (#17800446)
More importantly, many (most?) GNU projects don't care about man pages:

https://www.gnu.org/prep/standards/html_node/Man-Pages.html

Re:Um – Create your own man pages so you can remember how to... by jplayer01 on Monday August 20, 2018 @12:19PM (#17801226)
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.

Re:Um – Create your own man pages so you can remember how to... by KC8ZKF on Monday August 20, 2018 @01:03PM (#17801634)
GNU deprecates man pages in favor of texinfo, not no documentation at all.

https://www.gnu.org/prep/standards/html_node/Documentation.h...

Re:Um – Create your own man pages so you can remember how to... by owaty on Monday August 20, 2018 @12:52PM (#17801517)
That page is specific to man pages, not to documentation in general.

See https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm...

Re:Um – Create your own man pages so you can remember how to... by S-E-P on Monday August 20, 2018 @10:26AM (#17800144)
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)

Re:Um – Create your own man pages so you can remember how to... by Sir_Cmpwn on Monday August 20, 2018 @12:06PM (#17801080)
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.
Re:Um – Create your own man pages so you can remember how to... by kitsunesoba on Monday August 20, 2018 @12:58PM (#17801580)
I don’t think being afraid of the process is the problem. It’s more about how unnecessarily manual the process is paired with the possibility of your patch’s email thread getting buried never to be seen again or worse, its reviewer abandoning it halfway through the review process with no easy way for someone else to pick it up.

That’s not to say that Github pull requests and the like are perfect (far from it) but it’s undeniable that they smooth the process quite considerably and make contribution far more accessible.

Re:Um – Create your own man pages so you can remember how to... by Sir_Cmpwn on Monday August 20, 2018 @01:01PM (#17801615)
People are busy. If you want your patch considered, you should be bumping it and reaching out to people who can merge it. Man page improvements are generally a shoe-in, just get someone to pay attention to it for a few minutes and it'll get in.
Re:Um – Create your own man pages so you can remember how to... by mikebenfield on Monday August 20, 2018 @01:37PM (#17801966)
The process you're describing in this comment is exactly the outdated approach people are saying they don't want to do.
Re:Um – Create your own man pages so you can remember how to... by Sir_Cmpwn on Monday August 20, 2018 @02:32PM (#17802530)
It's not like this isn't a problem for GitHub, either. Pull requests go ignored, too.
Re:Um – Create your own man pages so you can remember how to... by mdaniel on Monday August 20, 2018 @12:58PM (#17801578)
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
Re:Um – Create your own man pages so you can remember how to... by Sir_Cmpwn on Monday August 20, 2018 @01:02PM (#17801622)
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.
Re:Um – Create your own man pages so you can remember how to... by oblio on Monday August 20, 2018 @02:28PM (#17802474)
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.
Re:Um – Create your own man pages so you can remember how to... by Sir_Cmpwn on Monday August 20, 2018 @02:33PM (#17802533)
Higher friction => higher quality contributions.
Re:Um – Create your own man pages so you can remember how to... by aktau on Monday August 20, 2018 @04:22PM (#17803588)
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.
Re:Um – Create your own man pages so you can remember how to... by Sir_Cmpwn on Monday August 20, 2018 @05:18PM (#17804060)
1. One account for manifesting your chosen identity, which you likely already have.

You also have an email address, so. You need an email address to get a GitHub account, so technically it's harder to set up GitHub.

2. One common way of getting the source code and sending diffs/patches (read: PRs).

This is built into git. Don't need GitHub for either.

Re:Um – Create your own man pages so you can remember how to... by aktau on Monday August 20, 2018 @06:18PM (#17804538)
It looks like you think that older approaches to open-source collaboration (like many of the GNU projects are using) are more or less as user-friendly as GitHub. I don't have the data to prove that they aren't, just an intuition.

Perhaps the last argument I have is that I've heard a number of times about moving a project to GitHub (for example: the Go language or Vim the editor), but decidedly less often one hears of projects moving away from GitHub towards older forms (such as the wonderfully documented https://gcc.gnu.org/contribute.html). Despite the great documentation, I'm somehow not drawn to hacking on it to fix a small glitch, due to the overhead that entails. Mind, some of that overhead would be incurred just once, as it is general to the mailing list approach to collaboration. That, I believe, is another advantage of a project being on GitHub: for almost all projects there's a standard way of sending your patch: make a pull request.

About your counterpoints:

1. True. I was thinking of the bug trackers many mailing-list oriented projects have, which often require creating accounts just to file a bug. 2. I was more referring to things like (1) where to find the clone URL and (2) how to send a patch (the make a PR button is always the same).

Removing friction (even small frictions) will enable fishing for the long tail of small fixes. On the other side, I do not believe large contributions are greatly affected by the differences between these systems.