| Let me rephrase: you assume that it makes sense for manpages to continue serving primarily as a reference—that this is the primary use-case people have for the standardized program documentation that ships with their distro packages. Shipping a reference to a binary with that binary may have made sense before the internet. But nowadays, it's the opposite. • Complex programs with many options have (sometimes dozens of) websites documenting them thoroughly. (Try searching with any search-engine for "wget mirroring", for example; the number and complexity of the results is overwhelming.) • Meanwhile, for the simple "corner-case" programs, you really hope that they shipped with docs—because seemingly nobody else out there on the web cares to bother documenting them. With a lot of these little programs, the only web doc you can find are, in fact, online mirrors of their man-page. For the popular-and-complex programs, man-pages are just redundant, because everyone will document what they did to achieve whatever. But for the simple-but-weird programs—the ones for which man-pages aren't just redundancies—if the man-page doesn't give usage, then nothing is going to give usage. Now, I can understand why man-pages for these little utilities are the way they are. These programs are usually created by a single author, so time spent writing docs is time not spent fixing bugs or scratching their itch or whatever else. And an options reference certainly is the "minimal normalized form" of documentation: it lets others brute-force combinatoric-search the space of invocations until they find some combination that Works For Them™. Basically, you can (through a lot of trial and error) generate a cookbook from an options reference. So the author probably doesn't feel a strong need to add anything beyond an options reference, because the people who really need to solve the problem their binary solves are willing to go to that effort. But if you're a distro downstream packager, and it's your job to make your distro easy for people to use, you should have every incentive to submit upstream patches to said author, with manpage additions of cookbook example usages resulting from your trial-and-error experimentation with their program. Annoyingly, you, as a distro packager, probably don't have time to do that trial-and-error experimentation, especially if the utility serves a niche use-case that you don't even understand. That—and not the fact that "manpages should be a reference and nothing more"—is most of the reason manpages continue to be the way they are. |
An ideal man page is concise, informative, and complete. Learning to read them is like learning to read scientific literature: a pain, but once you figure it out, you're at a higher level.