[_mlbt]

After using FreeBSD and OpenBSD, it is frankly shocking how bad Linux documentation is in comparison. On the BSDs every command, every program, every system call, and every configuration file are thoroughly documented in man pages and other guides. The FreeBSD Handbook in particular is a treasure. It more than makes up for some of the more difficult aspects of the OS by providing thorough and approachable documentation.

[noirscape]

It's a different model of development, leading to different expectations.

BSD ties the kernel and the software on top of it together pretty heavily, creating the expectation that the documentation should cover all of it.

Linux is meanwhile kernel and software kept separated, meaning that the documentation usually winds up assembled from separate tools, each with their own standards.

[ACS_Solver]

Yes, BSD is a single coherent system but so are many Linux distros. It's just that we've come to accept bad documentation as the norm for Linux-based tools. In my experience there's several types of problems that are very common for Linux tools:

* Extremely short documentation. Everyone has seen these, a tool where the man page exists but provides almost no actual information.

* Unfriendly reference-type documentation. GNU programs are often guilty of this, coreutils certainly comes to mind. On the upside, it's usually comprehensive. But it's not good - it's a short description followed by a sequential list of every option, so the functionality is described in detail but there are no usage examples, no list of the most common options, or anything like that. Great reference, poor usage documentation.

* Too much info about ancient systems or historical details. Yes, it's great that many of these utilities are portable and can run on different systems or work with files from different systems. The man pages for zip/unzip mention MS-DOS, Minix and Atari systems, while defining the zip format as "commonly found on MS-DOS systems". The man page for less explains that it's a program "similar to more(1)" - completely useless info now - and mentions that it has some support for hardcopy terminals, again information that's not important enough for the first paragraph in 2025.

* Poor keywords in the description. There's the theoretically useful apropos command. My Xorg wouldn't start so I tried to remember how to start my wifi up. apropos 'wlan|wi-fi|wifi|wireless' doesn't mention nmcli, which I was thinking of, though it does at least provide the much more difficult iw command.

* Technical project-specific jargon that makes it easy to find the solution - if you already know it, that is. For example, Xorg documentation generally doesn't use the word "resolution". It's not in the xrandr or Xserver man page, and in the xorg.conf page it's only a reference to virtual screens. Because X uses the term screen size. That's fine, understandable and even accurate but most people would first search for 'resolution'.

[eacnamn]

I for one really enjoy the historical anecdotes you get in the "NOTES", "PORTABILITY" or even "BUGS" sections. But I do realise that my context is mostly recreational, work doesn't really require glueing POSIX commands together.

[thewebguyd]

Yep. There is no "Linux Operating System." There's the Linux Kernel, and that kernel is used in tons of different OSes. It's sounds like a small nitpick but its a huge deal and a common misconception for those outside of the Linux world anytime a topic of unifying something in the Linux world comes up.

A shared or central wiki sounds nice, but could quickly end up too messy. Arch having its own makes sense, as in the case of Linux - the distro is the operating system. Arch is a different OS from Fedora, which is a different OS from Ubuntu, etc. Sure, there's a lot of overlap but they are each their own unique OS.

[bitwize]

I learned how to do NetBSD kernel hacking from just the man pages. They're still my first-line documentation on the NetBSD file system work I'm doing. The state of Linux documentation is appalling by contrast.

[hungmung]

Came in here to say the same thing. NetBSD should get more love.

Practically speaking ArchWiki has everything I'm likely to need as a poweruser, but it's not really all that comprehensive.

[bombcar]

GNU getting a burr up its ass that info pages were the future in whenever it happened did irreparable harm to Linux.

[cosmic_cheese]

Its consistent conventions also help a lot — it means learning a handful of things once, which can then be applied numerous other places (which as an aside, used to also be a strength of macOS). No need to even consult the manpage in many cases then.

An interesting but gargantuan project would be a Linux distro that maintains patches for all of its packages that standardize directory structures, config file locations, CLI argument order, etc.

[bongodongobob]

Linux != software that runs on Linux. Those are two completely different things.

[MobiusHorizons]

I don’t think anyone is confused about this. Linux is a shorthand for the family of Unix like operating systems that use Linux as the kernel. The only ambiguity in this shorthand is if android or chrome os are being referenced, but it’s pretty clear from context that they are not relevant to the discussion.