7 ms·

Free software needs free documentation

97 points by crazypython 6y ago

ignoranceprior 6y ago
Kinda ironic that the GFDL isn't even considered a free license by Debian, at least when invariant sections are included.
- mattl 6y ago
  Invariant sections aren't free, surely?
  - duskwuff 6y ago
    Certainly not; invariant sections have the effect of limiting what modifications can be made to the work. The GFDL also places some weird restrictions on storage and distribution of the licensed work -- notably, it forbids the use of any "technical measures to obstruct or control the reading or further copying of the copies you make or distribute". Depending on how strictly you read this, this could be interpreted as forbidding the use of encryption on filesystems containing GFDL documentation. https://wiki.debian.org/GFDLPositionStatement https://wiki.debian.org/GFDLPositionStatement
    - webmaven 6y ago
      > Depending on how strictly you read this, this could be interpreted as forbidding the use of encryption on filesystems containing GFDL documentation. That's a strange reading. I can see it interpreted as forbidding storing the document on a workstation that is locked-down to prevent exfiltration of sensitive data (and such a system would almost certainly also use an encrypted FS among other measures), but forbidding the use of an encrypted FS per-se seems extreme. All an encrypted FS is doing by itself is ensuring that if you don't have access to the content, then you don't have access to the content. Nothing about the GFDL forces anyone to redistribute, it just ensures that recipients have the right to redistribute. By itself, an encrypted FS is no hindrance to redistribution.
deleted 6y ago
[deleted]
musicale 6y ago
Someone posted but then deleted an interesting comment about certain open source projects (OpenSSL possibly?) simply ignoring documentation contributions. The comment was something like "it was easier to get the documentation published as a printed book than to get the project to accept it."
musicale 6y ago
> The authors of the good manuals had written them for O'Reilly Associates, I see the bar is relatively... low. That being said, I expect the reason authors wrote for O'Reilly was so they could actually get paid. > The obstacle is that many users think that a proprietary manual is good enough—so they don't see the need to write a free manual. They do not see that the free operating system has a gap that needs filling. The biggest obstacle is probably either a) finding money to pay a good writer or b) finding a good writer who is happy to work without pay.
- PaulDavisThe1st 6y ago
  (c) finding a good writer able and willing to do the work under any conditions.
- cycloptic 6y ago
  I think you may have missed this part: >The problem with these manuals was not that O'Reilly Associates charged a price for printed copies—that in itself is fine.
  - Uehreka 6y ago
    If you’re saying people need to make their content available for free with an option to pay for a printed copy, then you’re telling them they can’t make money from their work, which is the thing at issue. And we can argue about whether authors of books about FOSS tools should embrace the same ethos as those tools’ developers, but it seems silly to hide the ball or act like there’s a win-win solution hiding in plain sight.
    - lelandbatey 6y ago
      I think what's being pointed out is more just a problem, no concrete solution (like "make their content available for free with an option to pay for a printed copy") is being prescribed. But if we are talking about prescriptive solutions, what I'd want that does all this is a pay-to-access documentation Wiki, where I and other users of the software can make changes (or at least propose changes) to those docs that we read and rely on.
bnkl 6y ago
Heaven forbid that free software authors want some sort of income. There are those that do not have a free office in MIT and a Mc Arthur grant. Apart from that, really only the leaders of big projects that were low hanging fruit in the 1990s and 2000s cash in massively, while most of the work is done by others.
ssivark 6y ago
”[...] The issues for writings are not necessarily the same as those for software. For example, I don't think you or I are obliged to give permission to modify articles like this one, which describe our actions and our views. But there is a particular reason why the freedom to modify is crucial for documentation for free software. When people exercise their right to modify the software, and add or change its features, if they are conscientious they will change the manual too—so they can provide accurate and usable documentation with the modified program. A manual which forbids programmers from being conscientious and finishing the job, or more precisely requires them to write a new manual from scratch if they change the program, does not fill our community's needs. While a blanket prohibition on modification is unacceptable, some kinds of limits on the method of modification pose no problem. For example, requirements to preserve the original author's copyright notice, the distribution terms, or the list of authors, are OK. It is also no problem to require modified versions to include notice that they were modified, even to have entire sections that may not be deleted or changed, as long as these sections deal with nontechnical topics.[...]”
- kome 6y ago
  very reasonable.
  - segfaultbuserr 6y ago
    Unfortunately, although the intentions are good, the additional restrictions imposed by GFDL creates a lot of compatibility problems in practice. Nowadays, the use of GFDL is no longer recommended by default. Unless you specifically need the unique features in GFDL, the best practice is to use Creative Commons 4.0, either CC BY or CC BY-SA (if you want stronger copyleft than CC BY-SA, even the use of GPL is better in terms of compatibility). The most prominent problem is the invariant sections and cover texts. It allows certain sections in a work to be unchangeable, such as the front-cover and back-cover texts, so that the information in the original publication won't be distorted. While it's very reasonable for a standalone book, but it would be a violation of basic expetation of free software if the documentation is to be treated as a subsection of the software itself. Thus, Debian packages software documentation separately, and classifies all docs with invariant sections as "non-free software". Also, the most common practice to publish documents under GFDL is to say "it's published under GFDL [version], with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts" to avoid the issue. But if you already do this, you don't really need GFDL. The second related problem is that the GFDL is an independent license, so it's incompatible with GPL in both directions. A GPDL manual cannot use GPL code, and a GPL program cannot use code from the GFDL manual. GPL code to a GFDL documentation is effectively proprietary, the only way to use them is invoke the rights of fair use, which only allows a very limited portion of code to be used. Another possible workaround is to dual-license all code in a GFDL manual. Even Eben Moglen, lead lawyer of the FSF, believes it's problematic. He says GFDL to him is like gravity to quantum mechanics. > [In GPLv3] By expressing LGPL as just an additional permission on top of GPL we simplify our licensing landscape drastically. It's like for physics getting rid of a force, right? We just unified electro-weak, ok? The grand unified field theory still escapes us until the document licences too are just additional permissions on top of GPL. I don't know how we'll ever get there, that's gravity, it's really hard. And the third problem is a practical one, the requirement of all works, even for those without Invariant Sections and Cover Texts, to include a full copy of the GFDL license. Again, while it's very reasonable for a standalone book, but it would be unsuitable for other types of creative works, such as short reference materials, maps, tour guide, or photos. The classic example is Wikipedia, if a reader ever wants to copy a section of the article or a single photograph, the inclusion of the full text of GFDL is legality required. It's why Wikipedia soon migrated to Creative Commons + GFDL to avoid this problem.
egypturnash 6y ago
Where's the GNU grant program to help fund the time it takes to write a good manual for something, then? Complete with people whose job at least partially involves finding folks who have had something worthwhile to say about a program, and convincing them that they want to spend the next few months of their lives expanding it into Serious Documentation?
- jraph 6y ago
  I don't think you got this right. It's more like, "documentation for free software should be free too", not really "free software should be documented".
jefft255 6y ago
I'm confused by this. Which free software has its documentation in a proprietary book? A textbook is not documentation². ROS, PyTorch, Tensorflow, Julia, Python, Emacs, you name it, all have free online documentation as well as non-free textbooks to learn those tools. Not sure about non-programming tools like Gimp or Blender. If the only way to learn how your software works is a print book, that's the issue, not the fact that this textbook is non-free. ²To me, documentation is a boring but exhaustive description of all the features in your software. A textbook is a nice introduction to the software in a linear fashion which doesn't necessarily aim to tell the whole story. After going through the textbook the user should be comfortable enough to look at the doc for the complete story. It's ok to want to profit from publishing a textbook for free software IMHO, just as you can build a consultancy on free software (see Red Hat, Savoir-faire Linux). It's merely charging for your expertise and time. Somehow saying that these book should be made available for free online takes away from that. Doesn't matter if you say that it's ok to pay for the print version.
- LukeShu 6y ago
  The article was originally written in 1996, and describes GNU policy. As a cultural artifact, it's been incredibly effective but is now outmoded, as what it describes is very solidly the norm, as you note. So today it serves as a statement of GNU policy and as a historical artifact, and isn't so much something that is relevant to today's readers. Since the article specifically calls out Perl: In the Perl 4 days (1991 until whenever Perl 5 (1994) gained critical mass), the O'Reilly book Programming Perl was the Perl documentation. Besides the book, the only other official documentation was the perl(1) man page, which (while lengthy at nearly 30,000 words) was not nearly as complete as the O'Reilly book.
  - jefft255 6y ago
    Oh, didn’t see the date. Perhaps one should add (1996) to the title.
  - Holylander 6y ago
    Thanks for the pointer, I was exactly asking myself "Was it written like in 90s?" Today the problem is too much information, not not enough of it.
jancsika 6y ago
> The biggest deficiency in free operating systems is not in the software—it is the lack of good free manuals that we can include in these systems. Aside from correcting trivial errors, this article is obsolete. If you have something compelling to document about a feature of some free software tool, publish it in a blog. It's 100x more discoverable and easier to publish than whatever ships with Gnu or whatever distro. Plus you get user-visible back-and-forth with timestamped comments on a blog, which at times are as valuable as the original (and often out-of-date) blog. Similarly, these comments are generally published with little friction, probably in less time than it takes an official doc maintainer to respond behind the scenes to a cranky doc question with "patches accepted."
- LukeShu 6y ago
  I read this comment yesterday, and didn't like it, and moved on (I didn't downvote). I was reminded of it while writing up my notes from an interview where we talked a bit about how to learn things and stay up-to-date. I realized that I was frustrated enough with this view that I needed to come back and comment. I HATE this viewpoint[1]. Blogs are so much worse. You have to go find some rando's blog, instead of just typing `man THING` or `info THING`[2] or (gasp) just asking the package manager for the listing of files in the package so you can see where it put the docs. Then, once you find it, you have to try to assess it for accuracy, maybe by reading through a bunch of comments; where in the official docs it gets reviewed by the very authors. And you have to try to assess it for up-to-date-ness, where in the official docs it just gets updated in place when things change. Or at the very least, instead of writing a new thing (a comment) that you have to hope that the next reader of the blogpost goes on to read, you file a PR against the official docs, to update it in-place. And then, if I have a related question that the blog post+comments don't quite answer, instead of scrolling up or down a couple paragraphs, I have to go start over. Writing blog posts instead of updating the actual docs is good for the blogger building their personal brand, but is bad for everyone actually wanting to learn about the thing. And sure, maybe it's easier to publish the blog post, because you don't need to get someone else to sign-off on it. But, that sign-off provides value to the reader. Your "patches accepted" comment is... weird. If you wrote the content in to the docs instead of writing it in to a blog post, that is a patch, so that's not how they'd reply. Like if you said "the docs should explain this", well yeah they might respond that way, but it's also way lower-effort than the blog post. If you put the same effort in to a PR that you'd put in to a blog post, then that won't happen. And maybe you will get a cranky maintainer who just says "no", then fine, take what you already wrote as the PR, and make it a blog post. At times on HN I've defended systemd's documentation; it's actually quite good if anyone ever bothered to read it. But I do have a big complaint with it: There are places where it just says "go read this 2009 post on Lennart's blog". That side-steps several of the issues: It's written by the known expert so is accurate, it's discoverable, it's trustworthy. But it is still bad, because it slowly gets more and more out-of-date, and if I, as a doc-contributor what to expand on or clarify or update something, I can't! Even though it doesn't have the normal "blog post" downsides, it still has the downsides that RMS talks about of non-Free documentation. Sorry if that was a little rude or rant-y. I originally read your comment and thought "that's reasonable, I disagree, but it's reasonable". But as I sat on it, I realized how much I disagreed with it, and thought I owed you an explanation of why I disagreed with it even when I initially thought it was reasonable. [1]: Though I guess I do agree that the article is obsolete; but because the lack of good free manuals is a much smaller problem now than it was in 1996, not because manuals are now obsolete. [2]: People love to complain about "info" manuals. Part of it is just that "`info` isn't `man`, and part of it is that the standard `info` command is kinda terrible (but if you're an Emacs user, `M-x info` is great, sucks for everyone else). But they often neglect to notice that info manuals can also produce HTML and PDF output, and when Googling things about GNU software, the HTML manual will often be the first hit, and will answer your question, and you won't ever realize that it was an allegedly-bad "info" manual. So even if you don't like local-docs or `info`, GNU's info manuals are discoverable just fine.
6510 6y ago
... then you find a 10 min bazillion view youtube video seemingly made by a 12 year old with 30 seconds worth of technology secrets being revealed and are unsure if to applaud or cry.
RandomWorker 6y ago
Our documentation is run from the repo which has it's open source license. I think because we have this folder "docs/" under the same repo our documentation is covered by our current license.
LukeShu 6y ago
(1996)
astan 6y ago
This is an old article, it should be marked as such.
er4hn 6y ago
One interesting place this hits is with ISO and ANSI standards. Let's discuss a not so hypothetical situation. You are a (free) developer trying to get your crypto library FIPS 140 certified. You want to do this because it is the US Federal standard for properly implemented crypto and it is hard to use in the Federal space without it. Ignoring the fact that you need a third party lab to validate your work, you quickly hit a documentation problem. FIPS standards are publicly available on NIST. That's great. But they in turn reference lots of other documents and expect you to follow the latest version of those documents. That is fine as long as other NIST documents are referenced. However references to ISO and ANSI documents do slip in. Each of those documents is a few hundred dollars a piece. You must comply with the contents of those documents in order to be certified. As a free developer, you now have a non-free documentation problem.
- LukeShu 6y ago
  That's even a problem with a few pieces of GNU software. The GNU documentation on how to use the software is Free, but if you want to contribute to it, you might need to acquire some pricey and non-Free specifications. For instance: If I wanted to work on modern C features in the C frontend in GCC, I'd probably need a copy of the ISO C18 spec, which would run me a bit over $200 (though in the case of the C standard I could instead get a late-2018 draft for free, and assume it didn't change too much between that draft and the final version). But note that this is a distinct issue from what RMS's essay is talking about! (The confusion owing to the word "free" being overloaded in English.) "Free documentation," as defined in the essay, means documentation that can be copied and modified, and RMS gives this as justification for those 2 freedoms: > Redistribution (including commercial redistribution) must be permitted, so that the manual can accompany every copy of the program, on line or on paper. > But there is a particular reason why the freedom to modify is crucial for documentation for free software. When people exercise their right to modify the software, and add or change its features, if they are conscientious they will change the manual too—so they can provide accurate and usable documentation with the modified program. A manual which forbids programmers from being conscientious and finishing the job, or more precisely requires them to write a new manual from scratch if they change the program, does not fill our community's needs. The ISO and ANSI standards that the software conforms to don't really meet either of those justifications: Copy: A user of GCC doesn't need to read the ASNI standard, the GCC manual is plenty good for explaining how to write C that GCC understands. A user of your crypto library doesn't need to read the FIPS standards to learn how to use your library. The standards are useful to the developers of the software, not the users; so the standards needn't accompany every copy of the program. Modify: A lone programmer working on GCC has no business editing the standards. Agreement between multiple parties is the entire point of the standard; it doesn't make sense to grant permission for just anyone to make edits. RMS is generally pretty clear there are many types of writing that he doesn't believe you are obliged to grant permission for others to edit. That said, the situation with non-gratis standards is problematic, it means that there's a monetary moat around contribution. But this is an entirely orthogonal problem to what's discussed in "Why Free Software needs Free Documentation".
pabs3 6y ago
I wish RedHat would publish the git repositories containing asciidoc source files for their public and freely licensed (CC-BY-SA) documentation (like their LVM docs), does anyone know any of the higher-ups in RedHat who could force this to happen? https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_logical_volumes/index https://access.redhat.com/documentation/en-us/red_hat_enterp...
- webmaven 6y ago
  > I wish RedHat would publish the git repositories containing asciidoc source files for their public and freely licensed (CC-BY-SA) documentation (like their LVM docs), does anyone know any of the higher-ups in RedHat who could force this to happen? Aside: I really wish the CC licenses had a (possibly optional) requirement for making the document's source format (or, "preferred form for making modifications") available. So many ostensibly Free-as-in-Speech technical documents are only ever distributed as PDFs that are an error-prone pain to convert back into an editing-friendly format, or for that matter, to convert to almost any other widespead end-user format, such as EPUB.
  - pabs3 6y ago
    This is a significant advantage of the GNU GPL that I also wish more licenses had adopted.
doggydogs94 6y ago
If you don’t like the documentation (or lack of free documentation), write the code and documentation yourself; fixes the problem.
DoreenMichele 6y ago
Not that I expect this to get a lot of eyeballs, but as a writer who spends a lot of time on HN, I think I may know a place to begin here: https://news.ycombinator.com/item?id=25039648 https://news.ycombinator.com/item?id=25039648

97 points by crazypython 6y ago

Kinda ironic that the GFDL isn't even considered a free license by Debian, at least when invariant sections are included.

mattl 6y ago
Invariant sections aren't free, surely?
- duskwuff 6y ago
  Certainly not; invariant sections have the effect of limiting what modifications can be made to the work. The GFDL also places some weird restrictions on storage and distribution of the licensed work -- notably, it forbids the use of any "technical measures to obstruct or control the reading or further copying of the copies you make or distribute". Depending on how strictly you read this, this could be interpreted as forbidding the use of encryption on filesystems containing GFDL documentation. https://wiki.debian.org/GFDLPositionStatement https://wiki.debian.org/GFDLPositionStatement
  - webmaven 6y ago
    > Depending on how strictly you read this, this could be interpreted as forbidding the use of encryption on filesystems containing GFDL documentation. That's a strange reading. I can see it interpreted as forbidding storing the document on a workstation that is locked-down to prevent exfiltration of sensitive data (and such a system would almost certainly also use an encrypted FS among other measures), but forbidding the use of an encrypted FS per-se seems extreme. All an encrypted FS is doing by itself is ensuring that if you don't have access to the content, then you don't have access to the content. Nothing about the GFDL forces anyone to redistribute, it just ensures that recipients have the right to redistribute. By itself, an encrypted FS is no hindrance to redistribution.

deleted 6y ago

[deleted]

musicale 6y ago

Someone posted but then deleted an interesting comment about certain open source projects (OpenSSL possibly?) simply ignoring documentation contributions. The comment was something like "it was easier to get the documentation published as a printed book than to get the project to accept it."

musicale 6y ago

> The authors of the good manuals had written them for O'Reilly Associates, I see the bar is relatively... low. That being said, I expect the reason authors wrote for O'Reilly was so they could actually get paid. > The obstacle is that many users think that a proprietary manual is good enough—so they don't see the need to write a free manual. They do not see that the free operating system has a gap that needs filling. The biggest obstacle is probably either a) finding money to pay a good writer or b) finding a good writer who is happy to work without pay.

PaulDavisThe1st 6y ago
(c) finding a good writer able and willing to do the work under any conditions.
cycloptic 6y ago
I think you may have missed this part: >The problem with these manuals was not that O'Reilly Associates charged a price for printed copies—that in itself is fine.
- Uehreka 6y ago
  If you’re saying people need to make their content available for free with an option to pay for a printed copy, then you’re telling them they can’t make money from their work, which is the thing at issue. And we can argue about whether authors of books about FOSS tools should embrace the same ethos as those tools’ developers, but it seems silly to hide the ball or act like there’s a win-win solution hiding in plain sight.
  - lelandbatey 6y ago
    I think what's being pointed out is more just a problem, no concrete solution (like "make their content available for free with an option to pay for a printed copy") is being prescribed. But if we are talking about prescriptive solutions, what I'd want that does all this is a pay-to-access documentation Wiki, where I and other users of the software can make changes (or at least propose changes) to those docs that we read and rely on.

bnkl 6y ago

Heaven forbid that free software authors want some sort of income. There are those that do not have a free office in MIT and a Mc Arthur grant. Apart from that, really only the leaders of big projects that were low hanging fruit in the 1990s and 2000s cash in massively, while most of the work is done by others.

ssivark 6y ago

”[...] The issues for writings are not necessarily the same as those for software. For example, I don't think you or I are obliged to give permission to modify articles like this one, which describe our actions and our views. But there is a particular reason why the freedom to modify is crucial for documentation for free software. When people exercise their right to modify the software, and add or change its features, if they are conscientious they will change the manual too—so they can provide accurate and usable documentation with the modified program. A manual which forbids programmers from being conscientious and finishing the job, or more precisely requires them to write a new manual from scratch if they change the program, does not fill our community's needs. While a blanket prohibition on modification is unacceptable, some kinds of limits on the method of modification pose no problem. For example, requirements to preserve the original author's copyright notice, the distribution terms, or the list of authors, are OK. It is also no problem to require modified versions to include notice that they were modified, even to have entire sections that may not be deleted or changed, as long as these sections deal with nontechnical topics.[...]”

kome 6y ago
very reasonable.
- segfaultbuserr 6y ago
  Unfortunately, although the intentions are good, the additional restrictions imposed by GFDL creates a lot of compatibility problems in practice. Nowadays, the use of GFDL is no longer recommended by default. Unless you specifically need the unique features in GFDL, the best practice is to use Creative Commons 4.0, either CC BY or CC BY-SA (if you want stronger copyleft than CC BY-SA, even the use of GPL is better in terms of compatibility). The most prominent problem is the invariant sections and cover texts. It allows certain sections in a work to be unchangeable, such as the front-cover and back-cover texts, so that the information in the original publication won't be distorted. While it's very reasonable for a standalone book, but it would be a violation of basic expetation of free software if the documentation is to be treated as a subsection of the software itself. Thus, Debian packages software documentation separately, and classifies all docs with invariant sections as "non-free software". Also, the most common practice to publish documents under GFDL is to say "it's published under GFDL [version], with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts" to avoid the issue. But if you already do this, you don't really need GFDL. The second related problem is that the GFDL is an independent license, so it's incompatible with GPL in both directions. A GPDL manual cannot use GPL code, and a GPL program cannot use code from the GFDL manual. GPL code to a GFDL documentation is effectively proprietary, the only way to use them is invoke the rights of fair use, which only allows a very limited portion of code to be used. Another possible workaround is to dual-license all code in a GFDL manual. Even Eben Moglen, lead lawyer of the FSF, believes it's problematic. He says GFDL to him is like gravity to quantum mechanics. > [In GPLv3] By expressing LGPL as just an additional permission on top of GPL we simplify our licensing landscape drastically. It's like for physics getting rid of a force, right? We just unified electro-weak, ok? The grand unified field theory still escapes us until the document licences too are just additional permissions on top of GPL. I don't know how we'll ever get there, that's gravity, it's really hard. And the third problem is a practical one, the requirement of all works, even for those without Invariant Sections and Cover Texts, to include a full copy of the GFDL license. Again, while it's very reasonable for a standalone book, but it would be unsuitable for other types of creative works, such as short reference materials, maps, tour guide, or photos. The classic example is Wikipedia, if a reader ever wants to copy a section of the article or a single photograph, the inclusion of the full text of GFDL is legality required. It's why Wikipedia soon migrated to Creative Commons + GFDL to avoid this problem.

egypturnash 6y ago

Where's the GNU grant program to help fund the time it takes to write a good manual for something, then? Complete with people whose job at least partially involves finding folks who have had something worthwhile to say about a program, and convincing them that they want to spend the next few months of their lives expanding it into Serious Documentation?

jraph 6y ago
I don't think you got this right. It's more like, "documentation for free software should be free too", not really "free software should be documented".

jefft255 6y ago

I'm confused by this. Which free software has its documentation in a proprietary book? A textbook is not documentation². ROS, PyTorch, Tensorflow, Julia, Python, Emacs, you name it, all have free online documentation as well as non-free textbooks to learn those tools. Not sure about non-programming tools like Gimp or Blender. If the only way to learn how your software works is a print book, that's the issue, not the fact that this textbook is non-free. ²To me, documentation is a boring but exhaustive description of all the features in your software. A textbook is a nice introduction to the software in a linear fashion which doesn't necessarily aim to tell the whole story. After going through the textbook the user should be comfortable enough to look at the doc for the complete story. It's ok to want to profit from publishing a textbook for free software IMHO, just as you can build a consultancy on free software (see Red Hat, Savoir-faire Linux). It's merely charging for your expertise and time. Somehow saying that these book should be made available for free online takes away from that. Doesn't matter if you say that it's ok to pay for the print version.

LukeShu 6y ago
The article was originally written in 1996, and describes GNU policy. As a cultural artifact, it's been incredibly effective but is now outmoded, as what it describes is very solidly the norm, as you note. So today it serves as a statement of GNU policy and as a historical artifact, and isn't so much something that is relevant to today's readers. Since the article specifically calls out Perl: In the Perl 4 days (1991 until whenever Perl 5 (1994) gained critical mass), the O'Reilly book Programming Perl was the Perl documentation. Besides the book, the only other official documentation was the perl(1) man page, which (while lengthy at nearly 30,000 words) was not nearly as complete as the O'Reilly book.
- jefft255 6y ago
  Oh, didn’t see the date. Perhaps one should add (1996) to the title.
- Holylander 6y ago
  Thanks for the pointer, I was exactly asking myself "Was it written like in 90s?" Today the problem is too much information, not not enough of it.

jancsika 6y ago

> The biggest deficiency in free operating systems is not in the software—it is the lack of good free manuals that we can include in these systems. Aside from correcting trivial errors, this article is obsolete. If you have something compelling to document about a feature of some free software tool, publish it in a blog. It's 100x more discoverable and easier to publish than whatever ships with Gnu or whatever distro. Plus you get user-visible back-and-forth with timestamped comments on a blog, which at times are as valuable as the original (and often out-of-date) blog. Similarly, these comments are generally published with little friction, probably in less time than it takes an official doc maintainer to respond behind the scenes to a cranky doc question with "patches accepted."

LukeShu 6y ago
I read this comment yesterday, and didn't like it, and moved on (I didn't downvote). I was reminded of it while writing up my notes from an interview where we talked a bit about how to learn things and stay up-to-date. I realized that I was frustrated enough with this view that I needed to come back and comment. I HATE this viewpoint[1]. Blogs are so much worse. You have to go find some rando's blog, instead of just typing `man THING` or `info THING`[2] or (gasp) just asking the package manager for the listing of files in the package so you can see where it put the docs. Then, once you find it, you have to try to assess it for accuracy, maybe by reading through a bunch of comments; where in the official docs it gets reviewed by the very authors. And you have to try to assess it for up-to-date-ness, where in the official docs it just gets updated in place when things change. Or at the very least, instead of writing a new thing (a comment) that you have to hope that the next reader of the blogpost goes on to read, you file a PR against the official docs, to update it in-place. And then, if I have a related question that the blog post+comments don't quite answer, instead of scrolling up or down a couple paragraphs, I have to go start over. Writing blog posts instead of updating the actual docs is good for the blogger building their personal brand, but is bad for everyone actually wanting to learn about the thing. And sure, maybe it's easier to publish the blog post, because you don't need to get someone else to sign-off on it. But, that sign-off provides value to the reader. Your "patches accepted" comment is... weird. If you wrote the content in to the docs instead of writing it in to a blog post, that is a patch, so that's not how they'd reply. Like if you said "the docs should explain this", well yeah they might respond that way, but it's also way lower-effort than the blog post. If you put the same effort in to a PR that you'd put in to a blog post, then that won't happen. And maybe you will get a cranky maintainer who just says "no", then fine, take what you already wrote as the PR, and make it a blog post. At times on HN I've defended systemd's documentation; it's actually quite good if anyone ever bothered to read it. But I do have a big complaint with it: There are places where it just says "go read this 2009 post on Lennart's blog". That side-steps several of the issues: It's written by the known expert so is accurate, it's discoverable, it's trustworthy. But it is still bad, because it slowly gets more and more out-of-date, and if I, as a doc-contributor what to expand on or clarify or update something, I can't! Even though it doesn't have the normal "blog post" downsides, it still has the downsides that RMS talks about of non-Free documentation. Sorry if that was a little rude or rant-y. I originally read your comment and thought "that's reasonable, I disagree, but it's reasonable". But as I sat on it, I realized how much I disagreed with it, and thought I owed you an explanation of why I disagreed with it even when I initially thought it was reasonable. [1]: Though I guess I do agree that the article is obsolete; but because the lack of good free manuals is a much smaller problem now than it was in 1996, not because manuals are now obsolete. [2]: People love to complain about "info" manuals. Part of it is just that "`info` isn't `man`, and part of it is that the standard `info` command is kinda terrible (but if you're an Emacs user, `M-x info` is great, sucks for everyone else). But they often neglect to notice that info manuals can also produce HTML and PDF output, and when Googling things about GNU software, the HTML manual will often be the first hit, and will answer your question, and you won't ever realize that it was an allegedly-bad "info" manual. So even if you don't like local-docs or `info`, GNU's info manuals are discoverable just fine.

6510 6y ago

... then you find a 10 min bazillion view youtube video seemingly made by a 12 year old with 30 seconds worth of technology secrets being revealed and are unsure if to applaud or cry.

RandomWorker 6y ago

Our documentation is run from the repo which has it's open source license. I think because we have this folder "docs/" under the same repo our documentation is covered by our current license.

LukeShu 6y ago

(1996)

astan 6y ago

This is an old article, it should be marked as such.

er4hn 6y ago

One interesting place this hits is with ISO and ANSI standards. Let's discuss a not so hypothetical situation. You are a (free) developer trying to get your crypto library FIPS 140 certified. You want to do this because it is the US Federal standard for properly implemented crypto and it is hard to use in the Federal space without it. Ignoring the fact that you need a third party lab to validate your work, you quickly hit a documentation problem. FIPS standards are publicly available on NIST. That's great. But they in turn reference lots of other documents and expect you to follow the latest version of those documents. That is fine as long as other NIST documents are referenced. However references to ISO and ANSI documents do slip in. Each of those documents is a few hundred dollars a piece. You must comply with the contents of those documents in order to be certified. As a free developer, you now have a non-free documentation problem.

LukeShu 6y ago
That's even a problem with a few pieces of GNU software. The GNU documentation on how to use the software is Free, but if you want to contribute to it, you might need to acquire some pricey and non-Free specifications. For instance: If I wanted to work on modern C features in the C frontend in GCC, I'd probably need a copy of the ISO C18 spec, which would run me a bit over $200 (though in the case of the C standard I could instead get a late-2018 draft for free, and assume it didn't change too much between that draft and the final version). But note that this is a distinct issue from what RMS's essay is talking about! (The confusion owing to the word "free" being overloaded in English.) "Free documentation," as defined in the essay, means documentation that can be copied and modified, and RMS gives this as justification for those 2 freedoms: > Redistribution (including commercial redistribution) must be permitted, so that the manual can accompany every copy of the program, on line or on paper. > But there is a particular reason why the freedom to modify is crucial for documentation for free software. When people exercise their right to modify the software, and add or change its features, if they are conscientious they will change the manual too—so they can provide accurate and usable documentation with the modified program. A manual which forbids programmers from being conscientious and finishing the job, or more precisely requires them to write a new manual from scratch if they change the program, does not fill our community's needs. The ISO and ANSI standards that the software conforms to don't really meet either of those justifications: Copy: A user of GCC doesn't need to read the ASNI standard, the GCC manual is plenty good for explaining how to write C that GCC understands. A user of your crypto library doesn't need to read the FIPS standards to learn how to use your library. The standards are useful to the developers of the software, not the users; so the standards needn't accompany every copy of the program. Modify: A lone programmer working on GCC has no business editing the standards. Agreement between multiple parties is the entire point of the standard; it doesn't make sense to grant permission for just anyone to make edits. RMS is generally pretty clear there are many types of writing that he doesn't believe you are obliged to grant permission for others to edit. That said, the situation with non-gratis standards is problematic, it means that there's a monetary moat around contribution. But this is an entirely orthogonal problem to what's discussed in "Why Free Software needs Free Documentation".

pabs3 6y ago

I wish RedHat would publish the git repositories containing asciidoc source files for their public and freely licensed (CC-BY-SA) documentation (like their LVM docs), does anyone know any of the higher-ups in RedHat who could force this to happen? https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_logical_volumes/index https://access.redhat.com/documentation/en-us/red_hat_enterp...

webmaven 6y ago
> I wish RedHat would publish the git repositories containing asciidoc source files for their public and freely licensed (CC-BY-SA) documentation (like their LVM docs), does anyone know any of the higher-ups in RedHat who could force this to happen? Aside: I really wish the CC licenses had a (possibly optional) requirement for making the document's source format (or, "preferred form for making modifications") available. So many ostensibly Free-as-in-Speech technical documents are only ever distributed as PDFs that are an error-prone pain to convert back into an editing-friendly format, or for that matter, to convert to almost any other widespead end-user format, such as EPUB.
- pabs3 6y ago
  This is a significant advantage of the GNU GPL that I also wish more licenses had adopted.

doggydogs94 6y ago

If you don’t like the documentation (or lack of free documentation), write the code and documentation yourself; fixes the problem.

DoreenMichele 6y ago

Not that I expect this to get a lot of eyeballs, but as a writer who spends a lot of time on HN, I think I may know a place to begin here: https://news.ycombinator.com/item?id=25039648 https://news.ycombinator.com/item?id=25039648