Live data from Hacker News

Free software needs free documentation

gnu.org

41–48 of 48 posts

Re: Free software needs free documentation

#41
post #34
post #32

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 quickl…

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…

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.

Re: Free software needs free documentation

#42
post #29

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…

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…

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.

Re: Free software needs free documentation

#43
post #9

”[...] 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…

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?

Re: Free software needs free documentation

#44
post #35

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...

> 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") availab…

This is a significant advantage of the GNU GPL that I also wish more licenses had adopted.

Re: Free software needs free documentation

#46

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…

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.

Re: Free software needs free documentation

#47

> 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…

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.

Post reply on HN