The most offensive man pages are GNU project pages that effectively say, "for real documentation read the info page". Which, as someone that can never remember how to use info, is frustrating and just serves to piss me off...my first thought is "and a big fuck you to you, too". And then I look it up online so I don't have to read how to use info before I can read how to use the command I was looking for docs on.
I don't know if this is common practice anymore...I don't remember the last time I saw a defective man page like this, but I still remember it with great anger. I love GNU, but I hate the kind of condescension it takes to try to force someone to use a different tool because you believe it to be superior to the standard tool (when it's really not; I find info pages to be obtuse to create, and difficult to read).
GNU's stance on man pages is entirely correct! For real documentation, read the info page, but you rarely want real documentation, you just want a quick example or the command-line invocation syntax, or what a particular argument does. And 99% of the time, that will be in a man page.
The problem lies when you want to find something 1% of the time, and it's here that man pages become sprawling unindexed messes. For example, take a look at the man pages for perl or zsh: you'll have no chance finding anything, as those programs are so large that they need a wealth of documentation to go into them. At the same time, the info page for ls contains the things you rarely need to see such as exactly how things are sorted or the minute details of timestamp formatting. If this were all in the man page, you'd complain that you couldn't find anything in it.
I don't know, I always found the perl and zsh man pages to be rather pleasant. They were sprawling, sure, but having long ago given up on brevity, they have no fear of meticulously describing how a feature or flag works. And they're just man pages, so you don't need to read the manual-for-the-manual first like I always find myself doing when I'm forced to use info.
This fundamentally goes against the Unix philosophy though which is to provide small well-defined parts from which you can construct a complete solution from.
If you need a complex manual for a complex program, something is wrong.
What does this even mean? The name GNU itself is a joke.
I mean, the project wants to create an operating system that looks like UNIX, acts like UNIX, smells like UNIX, but from scratch with appropriate license that allows usage and access to source to anyone - so that the project doesn't get into legal trouble from whoever actually owns UNIX?
So drunk Stallman in 1981 says: "hik, let's call this, hik operhikating system GNU, hik, because it's not UNIX hik, but it sure looks like one, hik, but it's not, hik, but it kinda is hik, but it's not theirs hik it's everyone's hik". That's how I like to imagine it happened.
This was my impression as well after using OpenBSD, and when I pointed that out a while back on HN, it was pointed out that the core linux manpages have gotten much, much better in many cases[1]. In that respect, it may be another example of the GP comment.
1: My go-to example was always ifconfig, but linux's manpage for ip(8) really isn't that bad, as is actually the linux equivalent. Quality probably varies quite a bit based on the package that supplies the utility though, while OpenBSD's quality is fairly universal.
I wonder where the best place to report manpage bugs to is - for things like the builtin commands that may not have a single upstream. Does Ubuntu pull in a manpage update from Fedora? What about the other way around?
