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.