Earlier quoted context omitted.
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 documentati…
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.
* 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'.