Hacker News Reader

Comment by AndyMcConachie | Hacker News Reader

I wish I could upvote this 10,000 times.

Documentation isn't sexy or something. I don't know why Linux documentation sucks so much, but Redhat makes it suck must less. It takes lots of effort, money and writer hours to create the kind of documentation that Redhat maintains and businesses love documentation. A HOWTO or a FAQ are not documentation.

I actually prefer man pages and I dropped Linux for my personal project years ago in favor of OpenBSD (sometimes FreeBSD) precisely because their man pages are well maintained and really well written. I still have to interact with Linux sometimes and it's almost always Debian or Redhat. And I gotta say Redhat beats Debian on documentation.

View on HN

Well, part of the reason Linux documentation often isn't very good is that Red Hat doesn't treat documentation work as something that should be submitted upstream.

Their incentives favour creating Red-Hat-specific documentation, and this then reduces their users' incentive to improve upstream documentation.

There is a difference between package documentation and system documentation. Red Hat contributes package documentation upstream, but system documentation is by its nature distro-dependent.

Red Hat has contributed work that made distros more homogeneous (cough systemd cough) and excellent package documentation for that work; but also got flak for that...

They also have soooo many good articles (which are helpful not just to RHEL) behind a subscription wall. If you do a lot of work in the rpm ecosystem, they're like the Experts Exchange of Google search, with how many times you see an exact bug report, then you get to the page with a tease of your exact answer, but it fades into the login required bit.

If you download the Red Hat developer edition and run a "yum update" once every couple of months, then you will get access.

The developer edition is now more inconvenient, as you have to reapply once a year.

And it used to be open, until Oracle started closing their tickets for paid support with essentially cut-and-paste of access.redhat.com. That's why you can't have nice things.

>I don't know why Linux documentation sucks so much

because you need to pay competent people to do it. As FOSS is made up of lots of volunteers, lots of documentation isn't up to the standard we would want it to be.

Arch has excellent documentation. It definitely stands out.

Because most devs hate writing and maintaining documentation. Simple as that.

Since we're generalizing: most devs aren't great at writing documentation either.

Technical writing is a field of its own and it's important to recognize that. We could ever be so lucky if such writers were as attracted to free software as some developers are.

Reply on news.ycombinator.com