I’d say it’s not just that OpenBSD’s manpages are written well (though they are), but that the userland tools are simpler and have a better interface.

For example, people often bring up tar as a tool with a less‐than‐intuitive interface. Compare the manual to GNU tar with OpenBSD’s tar:

https://manpages.debian.org/stretch/tar/tar.1.en.html

https://man.openbsd.org/tar.1

Not only does GNU tar have a bewildering array of options that make reading through the manual a chore, it lists (as far as I can tell) only one example, and in a section devoted to explaining the many ways to specify command‐line options to tar. OpenBSD tar has a whole section dedicated to examples (as is typical for OpenBSD); the manual as a whole is clear, concise, and complete.

Another example: GnuPG versus OpenBSD’s signify.

https://manpages.debian.org/stretch/gnupg2/gpg2.1.en.html

There’ve got to be over 100 options in there. And although it helpfully places --sign first (and --clear-sign, and --detach-sign, and --encrypt, and --symmetric, and --store, before it finally gets to --decrypt), let’s be real: anyone who’s not already comfortable with encryption software will be completely intimidated by this manual, which is 175 (!) page‐downs in a 80×24 terminal.

Contrast with signify:

https://man.openbsd.org/signify.1

The description section starts with the four major operations (sign file, verify file, verify many files, generate key), and is again followed by an examples section.

Of course, the OpenBSD tools are much less featureful than the mainstream counterparts. But the reality is that most people, and certainly I myself, need only a few features in day‐to‐day life. Even being a real terminal junkie, I’ve only needed GNU tar specifically once or twice in the last ten years; and when I did, on OpenBSD, it was a mere “pkg_add gtar” away.

OpenBSD has a great self‐contained base system, with elegant tools and useful documentation, and an extensive package collection for when that’s not adequate. I continue to use it because it serves my needs as a primary driver, and the interface is just so gosh darn pleasant to use.

It’s slightly disingenuous of you to compare the GNU man page to the OpenBSD man page, since while the OpenBSD man page is the official documentation, the GNU man page is not. As clearly stated in the GNU man page for tar: “This manpage is a short description of GNU tar. For a detailed discussion, including examples and usage recommendations, refer to the GNU Tar Manual […]”, and it gives a link to it: https://www.gnu.org/software/tar/manual/tar.html#SEC1

If you had compared the OpenBSD man page to that, it would be a more fair comparison.

“Disingenous” suggests malice. That is both unkind and untrue. I had simply forgotten.

In any case, the info page is far larger than the already‐large manual page, which I think only further illustrates one of my points, that the software is itself intimidatingly complex.

That GNU hates man pages and instead provides documentation in an obscure and long-winded format is part of the problem, not an excuse.

Worse, it fails the "requires an internet connection" test.

Raise your hand if good man pages have helped you out of a fubar situation. raises hand

The Info documentation is installable locally, and is perfectly readable without an Internet connection with a suitable tool, like Emacs.

Seems that OpenBSD folks understand what the page in manpage means. Too bad they do not have something similar to info for full manuals (yes, you hate the default GNU info viewer, i know, my point is about the hypertext format with indexing and working as an ebook file that takes advantage of the fact that computers are interactive and does not try to simulate dead trees).

OpenBSD manpages are written in a semantic format, -mdoc, that readily converts to HTML with inter‐ and intra‐document hyperlinks, and facilitates searching and hyperlinking even from within the terminal (via more(1)’s tags support).

I know, but writing a coherent manual is a different task than writing a short reference page, especially if you want to include more content than just a reference (e.g. user guides or tutorial sections) and writing text that assumes inline hyperlinking is always available.

Note that this isn't about it being technically impossible, you can certainly do it, but it isn't the right tool for the job - a dedicated manual reader provides a better UX here (and the failure of GNU info to provide a user friendly experience is, IMO, the reason manpages are abused so much in Linux).

You're talking about the grossly-misnamed (since large portions of it do not contain any questions) OpenBSD FAQ, which is where guide and tutorial stuff is to be found.

BSDs (and some others) come with variously-named Handbooks. OpenBSD has the aforementioned. FreeBSD has a Handbook. So do DragonFly BSD, NetBSD, and others. They are distinct from the user manuals, which are the reference doco. They are, indeed, hyperlinked. Already.

* OpenBSD FAQ: http://openbsd.org/faq/index.html

* NetBSD Guide: https://netbsd.org/docs/guide/en/

* FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html

* DragonFly BSD Handbook: https://www.dragonflybsd.org/docs/handbook/

* GhostBSD Handbook: https://wiki.ghostbsd.org/index.php/GhostBSD_User_Handbook

* MicroBSD Handbook: http://damnsmallbsd.org/MicroBSD/handbook/

* OpenIndiana Hipster Handbook: http://docs.openindiana.org/handbook/getting-started/

* old TrueOS User Guide: https://trueos.org/handbook/trueos.html

I'm not talking about any specific guides or manuals, but yes the OpenBSD FAQ, FreeBSD Handbook, etc are the sort of manuals i am talking about. But those are not made in manpage format and at least the OpenBSD FAQ HTML pages seem to be edited by hand. And since those are in HTML (at least the OpenBSD one, i didn't look into the others) they lack the indexing and ebook-like reading features that something like info provides (e.g. there are no browsing links - there used to be a pseudostandard with special <link> tags, but it was only ever supported by classic Mozilla/SeaMonkey and it never caught on).

EDIT: i see some of those are authored in DocBook but still info files can in theory be written in DocBook too. The main focus of my comments here is the end user format and viewer capabilities, not the authoring format (and honestly i'm not a big fan of info format with its hardcoded text formatting).

Since I got frustrated with linux man pages a lot, I am glad to see OpenBSD does it different. (one of the reasons why I finally want to give it a try)

The tar example is indeed much cleaner.

But it seems to be a bit old ...

"A tar archive is often stored on a magnetic tape, but can be stored equally well on a floppy, CD-ROM, or in a regular disk file"

Not that it hurts much, though.

See the blame on tar.1 [0] : documentation does not change very much...

[0] https://github.com/openbsd/src/blame/f84583fe5d7899ab1504dc1...

If the software and the documentation differ, that's a bug. If you don't understand the docs, there's a bug in the documentation.

OpenBSD does not like bugs :-)

Good examples are critical. Examples are not a substitute for a thorough explanation, but they can make utilities so much easier to understand. If you're writing technical documentation, please include some examples starting with the simplest use cases.

> Another example: GnuPG versus OpenBSD’s signify.

Apache/nginx/whatever versus OpenBSD's httpd.

[a suite of various software] versus OpenBSD's relayd.

iptables vs OpenBSD's pf (that's the "pf" in "pfSense").

OpenSSL vs OpenBSD's libtls.

Said much better than I could. :)

I don't know anyone who relies on man pages for Linux. I know a lot of people who use man pages almost exclusively for OpenBSD.

Yes, they are there for system calls, but also for applications -- depending on your definition of end-user applications, since some of what Linux considers "end-user" are, as TFA mentions, first-class applications that ship with OpenBSD.

I don't think the differences can be resolved with copy and paste since many Linux man pages deal with programs that are very different under the hood than those with the same or similar names in OpenBSD. I also don't think it's unfair or arrogant to consider OpenBSD's man pages to be the standard of what man pages should be, btw.

Search one or two of your favorites and see for yourself: https://man.openbsd.org

I would say it's both the user application and the system calls.

Here is the man page of the driver for the wireless card in my laptop https://man.openbsd.org/iwm.4

It's clear and concise, has links to the related tools that I might need to get the card working.

Is there a similar man page for Linux? I'm not sure, honestly.

Copy and paste? You'd have to copy and paste the whole driver for a start.

It cannot be resolved with some copy and paste.

Take "ps", for example. The BSD "ps" program is fundamentally different to the Linux "ps" program. It's also, quite importantly, different to what the Linux "ps" manual erroneously claims the BSD "ps" to be.

* https://manpages.debian.org/testing/procps/ps.1.en.html

* http://man.openbsd.org/ps

* http://netbsd.gw.com/cgi-bin/man-cgi?ps

* https://freebsd.org/cgi/man.cgi?query=ps

* https://unix.stackexchange.com/a/511530/5132