(Replying to PARENT post)

My perspective is skewed since I only get the questions that the documentation doesn’t answer, but I support someone who uses OpenBSD and the documentation is far from perfect. Some complaints that spring immediately to mind:

The man pages sometimes document things only by implication, or with confusing wording, such that if you already know the answer it makes sense, but if you don’t it’s near-impossible to find out. (To be fair, this affliction is definitely not exclusive to OpenBSD’s manpages.)

From what I can figure out, their 'ksh' is a vendored copy that they forked and made a bunch of changes to without ever updating the version string, so despite claiming to be “PD KSH v5.2.14 99/07/13.2” it’s got 20 years of patches added on top and won’t match any ksh you’ll find anywhere else. This is not explained anywhere that I could find.

There are some questions in the installer about 802.11 setup which are terse to the point of incomprehensibility and AFAICT entirely undocumented. (I had to go rummaging around in the source code and read the installer script to figure out what it was trying to get me to do.)

A particular peeve is that the sh and ksh manpages are completely different, despite documenting the same program. (They’re the same binary, with the non-POSIX bits left out of the sh manpage.) It’s particularly frustrating that there are some things documented well in one but poorly in the other, so once you’ve found the same documentation on both sides you still have to figure out what’s actual differences and what’s just bad phrasing.

OpenBSD’s maintainers also seem very insular and their mailing lists have a reputation for being very abrasive, so it’s also very intimidating to propose improvements; as a result these papercuts stick around (not being very obvious to the developers, who already know how these things work and so miss them) and continue to mar the polish.

👤wolfgang42🕑3y🔼0🗨️0

(Replying to PARENT post)

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.
👤wheresmycraisin🕑3y🔼0🗨️0

(Replying to PARENT post)

It really, really is.

The comprehensive and well-written man-pages are one of the reasons why OpenBSD feels so "complete". In German, you'd say "aus einem Guss", which almost literally translated means "from a single mold".

Linux often feels like a bunch of different things thrown together (which it always was), and the quality, or even just existence, of the documentation differs accordingly.

👤anyfoo🕑3y🔼0🗨️0

(Replying to PARENT post)

To compare and contrast, when I was trying to get wifi up and working on my UltraSparc laptop, I read the OpenBSD man page for ipconfig. While very long, it got me up and running in short order. No Google required.

On the Linux side, there was a Linux utility mentioned on HN and it was broadly praised. So one "pamac install" later, I was reading its man page. I had to resort to Google because I couldn't even tell what the program was supposed to do from its own manual.

👤cptnapalm🕑3y🔼0🗨️0

(Replying to PARENT post)

Because they understand the value it holds and put in the work to maintain it.

Documentation is expensive. Good documentation is more expensive, requires different skillsets than most engineers have, and requires a bit of an organizational commitment to make work.

That last part is more difficult in Linux-land than BSD-land, which is only a partial excuse. The main reason it almost universally sucks is that people put up with it, so managers are more than happy to cut those expensive tech writers.

👤_jal🕑3y🔼0🗨️0

(Replying to PARENT post)

BSD folks just want to make the world a better place. And I love them for it.
👤rwaksmunski🕑3y🔼0🗨️0

(Replying to PARENT post)

Most official GNU project software usually has pretty solid GNU info documentation. But, of course, GNU/Linux has a lot of major not-GNU pieces like the Linux kernel and systemd.

I can't place it, but I seem to remember Richard Stallman stating in some early GNU project goals that he'd seen much software usefulness hindered by poor documentation and made it a notable priority for the GNU project to have good documentation from the beginning.

GNU manuals online: https://www.gnu.org/manual/

👤theonemind🕑3y🔼0🗨️0

(Replying to PARENT post)

As much as I love Debian, I wish it had better documentation. Having said that I haven’t tried to contribute to it at all, so I guess I can’t complain.
👤noncoml🕑3y🔼0🗨️0

(Replying to PARENT post)

Two reasons:

1. In general, new programs, and updates to extending programs, tend not to get committed without the requisite manual pages or related manual page updates.

2. "Bugs" in OpenBSD's manual pages are treated no differently than bugs in other areas of the source tree. Find a problem in a manual page? Submit a diff file for it and it'll get reviewed and committed.

👤binkHN🕑3y🔼0🗨️0

(Replying to PARENT post)

The OBSD docs are good... if you know what you're looking for and are familiar with UNIX already. For a beginner, they are cumbersome, hidden, and annoying to parse.

Good docs look like Tailscale[0] and that similar style where it has the Getting Started at the beginning, along with a nice menu tree on the side that gives an overview and provides easy navigation. You shouldn't need to know what you are looking for when you are learning a platform.

[0] https://tailscale.com/kb/

👤status200🕑3y🔼0🗨️0

(Replying to PARENT post)

This article only convinces me that the OpenBSD documentation is bad, for three reasons.

First, there are seven listed sources for documentation. Seven places I might have to look through to get the answers I need. I cannot imagine a reason to have more than two - "static" documentation (the four kinds of docs in the Divio documentation system) and release notes.

Second, there's no mention of awareness of the distinction between the four kinds of documentation (https://documentation.divio.com/), and lots of discussion on the implementation details of man pages but nothing on the actual content. Man pages are pretty well-known for being decent references, but often lacking how-to guides and explanation, and having terrible/nonexistent tutorial information. This makes me think that the author is confusing "documentation" with "reference manuals".

Third, the lack of a community wiki is explicitly counted as a feature. It's not. Users need a place where they can collaborate with other users, and quickly write down their observations and hacks and problems while they're trying to get their job done - they don't have time to start a lengthy conversation with the mailing list developers or go through an involved process for patching the official documentation. Source: me, a user who has to work in a corporate environment and whose job is not working on OpenBSD, as well as many of my co-workers who often don't even take a few minutes to edit the wiki when they find a problem or fix.

👤throw10920🕑3y🔼0🗨️0

(Replying to PARENT post)

In part because they do it for the love of the OS. Now if only they would support these "mongrel" video cards...
👤balentio🕑3y🔼0🗨️0

(Replying to PARENT post)

As someone who has spent quite a bit of time documenting the internal workings (i.e. design) of various software and systems and much less so user interfaces (ain't nobody got time for that), it is interesting to note that the opposite is what is available in open source projects.

I mean, it makes sense since the internals are probably moving more than the interfaces and since everybody reads code anyway they can just do that. On the other hand, design documentation allows one to quickly figure out how a particular feature works, which is more tedious to do from just reading code. Barrier for use is lower, but barrier for contributing is higher, or something...

👤zppln🕑3y🔼0🗨️0

(Replying to PARENT post)

Simple answer, because it's a single OS with a single focus and centralized development. Compare the Arch WIKI to the OpenBSD docs and marvel at the difference in scale.

There are downsides to it too, Linux has a lot faster development and broader compatibility but this also results in more complex amd harder to maintain docs.

👤INTPenis🕑3y🔼0🗨️0

(Replying to PARENT post)

BSDs tend to have pretty good docs in general. Take a look at NetBSD's internals for instance: https://www.netbsd.org/docs/internals/en/index.html
👤Sin2x🕑3y🔼0🗨️0

(Replying to PARENT post)

How often does it have to be updated/changed?

Who's updating it? Volunteers, paid contributors, developers?

👤bluedino🕑3y🔼0🗨️0

(Replying to PARENT post)

possibly for the same reason the Arch wiki is so good.
👤gjvc🕑3y🔼0🗨️0

(Replying to PARENT post)

I’m happy the title isn’t “The unreasonable effectiveness of the OpenBSD’a documentation”.
👤nesarkvechnep🕑3y🔼0🗨️0

(Replying to PARENT post)

i use arch btw
👤kiprasmel🕑3y🔼0🗨️0

(Replying to PARENT post)

It is not, it's is terrible.
👤opentokix🕑3y🔼0🗨️0

(Replying to PARENT post)

Not even going to click, The BSDs have better documentation because their business model does not depend on selling texinfo manuals.
👤nmz🕑3y🔼0🗨️0