Hacker News Reader

Comment by wheresmycraisin | Hacker News Reader

FreeBSD handbook is also very, very good. I think that the BSD's are each more or less self-contained has something to do with it. You can read everything about system services, for example, in the handbook without having to chase down systemd blog posts and compensate for various differences between versions and distros.

View on HN

They are indeed very good but the pace of change being slower than Linux also makes it easier to keep things updated.

It's also that the process of change requires documentation. You won't get changes committed without it.

That seems like the root cause here. Why on earth isn't that the standard everywhere?

Because writing documentation isn't easy, and a lot of people who like writing code don't much like writing docs. So for an open source project "the documentation matters" has to be a conscious choice (a cultural value, if you like), which is actively enforced by (a) the regular devs pushing back on contributions which don't have docs and (b) those devs demonstrating a commitment to the value by upholding it themselves, ie writing docs for their own contributions.

Obviously "better docs" would be better for the users of software, but most people contributing to most open source projects (or indeed to most non-open source software!) are not doing so primarily for the altruistic goal of making users' lives easier. So the default position ends up being "do the stuff you find fun" or "do the stuff that your employer cares most about" or "do the stuff that fixes problems you personally are running into", which will often not be "great docs".

(I speak as somebody who's involved with an open source project whose documentation is overall not all that great and which doesn't have a "new changes must have docs" rule, so I don't mean to throw stones here -- just trying to argue that you should probably expect that poor docs are the norm and good ones the rarity.)

What if the slower pace is a conscious choice that makes the resulting documentation better and codebase more solid?

It's not (a conscious choice). There just are fewer people working on BSD. Linux has to handle an avalanche of developers wanting to merge their code.

Not being a disjointed mess of unrelated software helps too.

Any specific examples?

Every Linux distribution.

It’s decent but nowhere half as good as OpenBSDs documentation. Not complaining but it’s just not kept up to date in some places. Use of Jails for modern containers (eg using iocage) is a good example.

iocage is not part of the basesystem.

It's a bad example.

From a FreeBSD comment I made the other day:

> If you want to try FreeBSD just use the Handbook, it documents FreeBSD very well. That said betrays childish aspects e.g. they refuse to list that FreeBSD can run on Linux/KVM (the mere fact it can, I'm not talking in depth instructions).

(from id=32369189#32372408)

It lists KVM as an option in the very first part of Chapter 2 under the synopsis.

https://docs.freebsd.org/en/books/handbook/book/#bsdinstall

This is what I was talking about:

https://docs.freebsd.org/en/books/handbook/virtualization/

goes way back... (and into the contained bug report)

https://forums.freebsd.org/threads/please-give-some-ideas-ab...

Reply on news.ycombinator.com