Free software needs free documentation
gnu.org
gnu.org
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.
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".
It is an unfortunate insight that the problems with ISO docs affect GNU software as well.
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.
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.
PS: I particularly enjoyed the unification/gravity analogy btw :-D >.<
It's more like, "documentation for free software should be free too", not really "free software should be documented".
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.
>The problem with these manuals was not that O'Reilly Associates charged a price for printed copies—that in itself is fine.
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.
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.
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
It's also a great way to convince consultants to avoid your software entirely.
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
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?"
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
(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.)
²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.
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.
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.
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.
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.
https://access.redhat.com/documentation/en-us/red_hat_enterp...
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.
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.
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."
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 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.