3 ms·

Open Source is not Free software, nor are most of the projects on GitHub intended for anyone to use. Consider how well documented projects under the GNU banner

Open Source is not Free software, nor are most of the projects on GitHub intended for anyone to use. Consider how well documented projects under the GNU banner are. Im sure this is a problem for some projects, but free software is not suffering because of it.

emiliobumachar 9y ago
"Nearly all open source software is free software, but there are exceptions." by Richard Stallman https://www.gnu.org/philosophy/open-source-misses-the-point.en.html https://www.gnu.org/philosophy/open-source-misses-the-point....
Ace17 9y ago
> Consider how well documented projects under the GNU banner are. For end-user documentation I would agree ; does it still stands for developer documentation?
rosser 9y ago
As well-documented as GNU software is — and it is! remarkably so — I think the project loses even more points for foisting the atrocity that is gnu-info on everyone. That is some abysmally "You will do it the way I want you to, and like it!" software. When I say `man foo`, do not suggest I look elsewhere, please.
- klodolph 9y ago
  So, they've written this amazing documentation system which generates info and HTML from the same sources, hosted all the HTML online and made it available as separate downloads, also made it accessible from the terminal using "info", and on top of that they've made a separate, shorter version of the documentation available as a man page and you say that they should lose points for it? Is this actually a problem for you? I'm genuinely curious. "Man" is only really usable when the pages are a reasonable size. Once they get too big, you end up spending most of your time grepping through it or paging forwards and backwards looking for the section you want. But apparently, gnu-info is an "atrocity". Why? Is it somehow morally wrong to ever try to make something better than "man"?
  - rosser 9y ago
    An "atrocity" is admittedly hyperbole, but when the man pages are vague, at best, and often just say "use info instead", that reads more "Do it the GNU way, or you're wrong," than, "Weren't we thoughtful to have given you all these alternatives?" Particularly when the former is not an uncommon attitude among FSF projects. I'll totally own that I'm reactive to that, but I really do think it's a little thoughtless, and a violation of the Principle of Least Surprise, to direct people elsewhere. I've been burned entirely too many times, trying to put out a fire, checking the man page to confirm I remember some argument or option correctly, and being told I'm looking in the wrong place. It's not that it's "morally wrong" to do that; it's that it introduces friction in a place where that might be — demonstrably has been, given my experience, which I know I'm not alone in having had — particularly painful. Sometimes, "grepping through the man page" is, in fact, the quickest route to the info you need...
    - klodolph 9y ago
      I mean, sure, it's nice to have the options documented in a man page. But most of the GNU projects have exactly this in addition to the full docs in info pages, multi-page HTML, and single-page HTML available for online or offline browsing. I think historically, there were some bad man pages for GNU projects which just pointed to info, but I haven't seen that happen recently.
      - rosser 9y ago
        Then that's improved markedly since the last time I bothered trying to `man foo` in the terminal for a GNU tool. I just go straight to the web, because at least there I can Ctrl-F properly. I'm not saying "don't even try to improve things", and I think that's a pretty un-generous read of my concern. I'm saying don't break people's expectations. Especially if those expectations might come into play in exigent circumstances, and create friction in a place where the user already has a problem that is far more important to them than whether they're using the output from most flexible documentation tool or not. Like I said, it sounds like that's improved. If so, I'm glad. But I have specifically been burned, and my time that was wasted was also someone else's money. Given that, a bit of, "Hey, guys? Maybe think about how this choice might affect people?" is, IMO, warranted.

emiliobumachar 9y ago

"Nearly all open source software is free software, but there are exceptions." by Richard Stallman https://www.gnu.org/philosophy/open-source-misses-the-point.en.html https://www.gnu.org/philosophy/open-source-misses-the-point....

Ace17 9y ago

> Consider how well documented projects under the GNU banner are. For end-user documentation I would agree ; does it still stands for developer documentation?

rosser 9y ago

As well-documented as GNU software is — and it is! remarkably so — I think the project loses even more points for foisting the atrocity that is gnu-info on everyone. That is some abysmally "You will do it the way I want you to, and like it!" software. When I say `man foo`, do not suggest I look elsewhere, please.

klodolph 9y ago
So, they've written this amazing documentation system which generates info and HTML from the same sources, hosted all the HTML online and made it available as separate downloads, also made it accessible from the terminal using "info", and on top of that they've made a separate, shorter version of the documentation available as a man page and you say that they should lose points for it? Is this actually a problem for you? I'm genuinely curious. "Man" is only really usable when the pages are a reasonable size. Once they get too big, you end up spending most of your time grepping through it or paging forwards and backwards looking for the section you want. But apparently, gnu-info is an "atrocity". Why? Is it somehow morally wrong to ever try to make something better than "man"?
- rosser 9y ago
  An "atrocity" is admittedly hyperbole, but when the man pages are vague, at best, and often just say "use info instead", that reads more "Do it the GNU way, or you're wrong," than, "Weren't we thoughtful to have given you all these alternatives?" Particularly when the former is not an uncommon attitude among FSF projects. I'll totally own that I'm reactive to that, but I really do think it's a little thoughtless, and a violation of the Principle of Least Surprise, to direct people elsewhere. I've been burned entirely too many times, trying to put out a fire, checking the man page to confirm I remember some argument or option correctly, and being told I'm looking in the wrong place. It's not that it's "morally wrong" to do that; it's that it introduces friction in a place where that might be — demonstrably has been, given my experience, which I know I'm not alone in having had — particularly painful. Sometimes, "grepping through the man page" is, in fact, the quickest route to the info you need...
  - klodolph 9y ago
    I mean, sure, it's nice to have the options documented in a man page. But most of the GNU projects have exactly this in addition to the full docs in info pages, multi-page HTML, and single-page HTML available for online or offline browsing. I think historically, there were some bad man pages for GNU projects which just pointed to info, but I haven't seen that happen recently.
    - rosser 9y ago
      Then that's improved markedly since the last time I bothered trying to `man foo` in the terminal for a GNU tool. I just go straight to the web, because at least there I can Ctrl-F properly. I'm not saying "don't even try to improve things", and I think that's a pretty un-generous read of my concern. I'm saying don't break people's expectations. Especially if those expectations might come into play in exigent circumstances, and create friction in a place where the user already has a problem that is far more important to them than whether they're using the output from most flexible documentation tool or not. Like I said, it sounds like that's improved. If so, I'm glad. But I have specifically been burned, and my time that was wasted was also someone else's money. Given that, a bit of, "Hey, guys? Maybe think about how this choice might affect people?" is, IMO, warranted.