Comment by _b8r0
8 years ago
People who complain about man pages tend not to understand man pages. Man pages aren't howto documentations. They're very specifically designed to document the different components of a command, call or configuration file.
OP is absolutely spot on about man pages being community driven. At least half the time someone complains to me about a man page, the man page is the wrong place to look. Usually, the answer they're looking for is in an info manual or somewhere like /usr/share/doc/.
>People who complain about man pages tend not to understand man pages.
That's their very issue with them.
>Man pages aren't howto documentations. They're very specifically designed to document the different components of a command, call or configuration file.
Then people who designed man pages didn't understand what the users want first and foremost: howto examples.
Besides, whether they document "the different components of a command" and whether they have howto examples is orthogonal. They could do all the formal documentation they want and still include howto examples.
That they don't (well, most don't, some man pages are decent enough to indeed include example sections) is their failure.
I don't think it's fair to say that the originators of man pages didn't understand what their users were looking for. In most cases, the authors are the users, and when they were first created, that was pretty much the only user base they had. Man pages are manual pages, not howto pages.
If I'm looking at a man page, it's pretty much always because I want to look up one of the options, not how to use the command itself. Adding that sort of howto clutter would make it a whole lot harder to use the pages properly. Why not leave man pages alone and just focus on info pages again (http://www.troubleshooters.com/linux/info.htm)? That was always the go-to for more verbose descriptions and has much more of a howto vibe about it.
>Man pages are manual pages, not howto pages.
Isn't that a made-up distinction though?
Who said manuals can't have representative examples for how to do certain tasks?
Product manuals (including software product manuals) almost always do. They don't just enumerate features and flags.
5 replies →
I pointed you directly at the correct sources of documentation: info pages (for most GNU software) and /usr/share/docs. These are the places where howtos belong, not man pages.
The issue isn't with man pages themselves. The issue is with the expectations sites, tutorials and users themselves set for man pages.
"People who complain about man pages tend not to understand man pages."
There could not be a more valid complaint. If the man pages aren't understandable, what program is supposed to explain them?
There isn't really a single program. Man pages have been built through convention by people who've taken the time to write them, at various points following guidelines from Ritchie et al. It's usually down to the OS to explain the purpose and function of man pages in their own documentation.
For some Operating Systems, man pages are exceptionally high quality (most notably the BSDs). For some, they're bilge, but such systems tend to have init managed through systemd.
Having said that, many OSes support info(1), which provides more detailed software manuals for many pieces of software.
Of course, there are actual physical locations for forms of documentation not in man format or structure. You can find out where such documentation lives on your system on most Unix-like OSes through man:
$ man hier