Free software needs free documentation(gnu.org)
gnu.org
Free software needs free documentation
https://www.gnu.org/philosophy/free-doc.html
47 comments
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".
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".
Thank you for elaborating on that. You are very right - I went with the wrong meaning of free there.
It is an unfortunate insight that the problems with ISO docs affect GNU software as well.
It is an unfortunate insight that the problems with ISO docs affect GNU software as well.
”[...] 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.[...]”
I think it would be good if there was a method to modify other people's writing. Imagine a news article where people can add references, statistics or prose to supplement the original. You could attribute each change to an author. I guess it is possible now if author's provided a licence for a work?
very reasonable.
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.
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.
> 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.
That way, the author of the manual can receive credit. And also the author can insert whatever sponsorships, dedications, and website URLs in there. And this is key, there are a lot of scam websites that just <iframe> existing websites and put ads outside the iframe.
CC-BY-SA is a weak copyleft– akin to LGPL while GFDL is akin to GPL.
That way, the author of the manual can receive credit. And also the author can insert whatever sponsorships, dedications, and website URLs in there. And this is key, there are a lot of scam websites that just <iframe> existing websites and put ads outside the iframe.
CC-BY-SA is a weak copyleft– akin to LGPL while GFDL is akin to GPL.
Thanks for a lucid explanation of the underlying mess. I now have a much better perspective.
PS: I particularly enjoyed the unification/gravity analogy btw :-D >.<
PS: I particularly enjoyed the unification/gravity analogy btw :-D >.<
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?
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".
It's more like, "documentation for free software should be free too", not really "free software should be documented".
> 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.
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.
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.
>The problem with these manuals was not that O'Reilly Associates charged a price for printed copies—that in itself is fine.
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.
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.
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.
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.
I'm not saying that and the article doesn't say that either. If anything it says the opposite, but the real focus of is asking for documentation writers to publish their source files. (odt/doc files, latex/rst/md sources, etc...) My personal opinion is that open source projects should probably do this, when a project is taking patches to the source and contributors can't also contribute to the docs then the docs will lag behind.
The problem listed in the article is specifically “freedom to copy, modify and redistribute”, not “free to have”
O’Reilly would be fine, if they allowed you to modify the book as you please — but they don’t; like licensed software, you’ve only paid to access the content, but you don’t really own it.
Basically every argument for FOSS is now being applied to the manual(s) as well
O’Reilly would be fine, if they allowed you to modify the book as you please — but they don’t; like licensed software, you’ve only paid to access the content, but you don’t really own it.
Basically every argument for FOSS is now being applied to the manual(s) as well
We really need an AGPL3 for documentation. If you read that documentation and then provide (consulting) services based on that knowledge, you really need to feed the profits back to the documentation authors.
The documentation AGPL equivalent would simply be that if you provide a modified copy of the docs remotely (eg online), you must still provide the documentation source and all rights to modify & redistribute further.
The AGPL just extends the GPL to apply in SaaS contexts — I don’t know how the documentation equivalent that would go anything close to modifying profit flow for consulting services
The AGPL just extends the GPL to apply in SaaS contexts — I don’t know how the documentation equivalent that would go anything close to modifying profit flow for consulting services
What you're proposing amounts to "if you read this, you must give us money". That's way outside the scope of a license and is completely unenforceable.
It's also a great way to convince consultants to avoid your software entirely.
It's also a great way to convince consultants to avoid your software entirely.
> The problem listed in the article is specifically “freedom to copy, modify and redistribute”, not “free to have”
If O'Reilly were to sell books on those terms, say in PDF+source form, what exactly would prevent "freedom to copy... and redistribute" from quickly turning into "free to have?"
If O'Reilly were to sell books on those terms, say in PDF+source form, what exactly would prevent "freedom to copy... and redistribute" from quickly turning into "free to have?"
The same arguments apply to FOSS, and can be addressed by all such pre-existing essays, arguments and flame wars. Again, this is just FOSS logic applied to documentation; the fundamentals are still the same.
Anyways taking FOSS money-making strategies, some can be applied here:
selling the tree, not the text (ala SaaS)
Justifying consultancy service based on writing/maintaining (ala redhat, technical bloggers, etc)
Selling the potential for more books/writing (ala patreon/Kickstarter)
Being paid to write because someone or a community needs it (ala corporate-backed OSS developers)
But anyways the monetization strategy doesn’t really matter, since the crux of the argument is that for FOSS to really be complete, the manuals need to be included in that definition; which seems to me entirely correct. Whether FOSS is a viable strategy in the first place is a separate question, but one RMS has spent a few decades making a case for, and a lot stronger of a case than I’d have given him if I heard him blathering on about it when he started
Anyways taking FOSS money-making strategies, some can be applied here:
selling the tree, not the text (ala SaaS)
Justifying consultancy service based on writing/maintaining (ala redhat, technical bloggers, etc)
Selling the potential for more books/writing (ala patreon/Kickstarter)
Being paid to write because someone or a community needs it (ala corporate-backed OSS developers)
But anyways the monetization strategy doesn’t really matter, since the crux of the argument is that for FOSS to really be complete, the manuals need to be included in that definition; which seems to me entirely correct. Whether FOSS is a viable strategy in the first place is a separate question, but one RMS has spent a few decades making a case for, and a lot stronger of a case than I’d have given him if I heard him blathering on about it when he started
I was replying to the parent post, which was replying to my previous post, where I suggested that authors probably chose to work with O'Reilly because they wished to be paid for their work.
(Though there may be other advantages such as print distribution, brand recognition, and iconic animal covers. Tim O'Reilly also seems like an interesting guy.)
(Though there may be other advantages such as print distribution, brand recognition, and iconic animal covers. Tim O'Reilly also seems like an interesting guy.)
(c) finding a good writer able and willing to do the work under any conditions.
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.
²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.
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.
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.
Oh, didn’t see the date. Perhaps one should add (1996) to the title.
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.
This flows naturally from US copyright: all creative works are copyrighted.
If the documentation is not explicitly licensed, then there is a risk that your distribution of the documentation is a violation.
This solves the problem of unknown documentation licensing, and makes the documentation a copyleft work product of its authors, which guarantees that any future derivative work that is released is also under a liberal license.
If the documentation is not explicitly licensed, then there is a risk that your distribution of the documentation is a violation.
This solves the problem of unknown documentation licensing, and makes the documentation a copyleft work product of its authors, which guarantees that any future derivative work that is released is also under a liberal license.
Kinda ironic that the GFDL isn't even considered a free license by Debian, at least when invariant sections are included.
Invariant sections aren't free, surely?
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
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
> 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.
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.
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.
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_enterp...
https://access.redhat.com/documentation/en-us/red_hat_enterp...
> 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.
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.
This is a significant advantage of the GNU GPL that I also wish more licenses had adopted.
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
[deleted]
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.
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.
If you don’t like the documentation (or lack of free documentation), write the code and documentation yourself; fixes the problem.
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."
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."
This is an old article, it should be marked as such.
... 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.
(1996)
> 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."
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."
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.
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.
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.