If you've used Linux, you may be aware that you can get help for a terminal command by typing man <command name>. This is one of those things that everyone tells Linux newbies, but never do themselves, because the manual pages (also called "man pages") seem completely useless compared to just Googling it.
This makes me very sad, because I believe if a piece of software requires you to go to the Internet to read its documentation, it effectively requires an Internet connection to work.By not having proper documentation, you gained a dependency on a search engine. I can't even use ls without Google.
There are a few problems with the man pages that I'd like to note.
Redundant Wall of Text with Zero Examples
In most cases, if you go read a command's man page, you get greeted with an exceedingly long wall of text that basically just tells you the same thing that --help would. What is surprising that manual writers manage to somehow nimbly avoid writing even a single usage example despite all the text they write.
Many times all I wanted is an example of how to do the most basic, obvious thing with a command, and there are no such examples. Examples are worth a lot more than all this text.
But surely, if the text isn't being used for usage examples for basic cases, it's being used to provide information far more valuable than a mere usage example? Unfortunately, that isn't the case.
In many cases, the man pages have incomplete information. For example:
-F, --classify[=WHEN] append indicator (one of */=>@|) to entries WHENman page ofls
What does this even mean? There is no explanation about what the indicators indicate, or even what is WHEN supposed to be, although, at the bottom of the page you do get an explanation for WHEN.
The WHEN argument defaults to 'always' and can also be 'auto' or 'never'.man page ofls
But how is the behavior of auto? It doesn't say that.
The manual also doesn't tell you what the column of ls -l (the long listing format) mean. I have no idea how are you expected to learn this stuff without Googling it.
Although I'm citing ls specifically here, this is the case with pretty much every command. You have no basic usage examples, and gaps in the information provided for advance use cases. The only place where the manual shines is in providing technical information about technical details for technical users. It really doesn't help the average user learn how to us the terminal commands at all.
Consequently, there have been efforts to provide alternatives for man pages, such as:
- [tldr.sh], a collaborative online resource for terminal commands.
- [bropages.org], same idea, now deprecated.
Wrong Information in Man Pages
In some cases, the man pages are for a completely different version of a program. Notably, the man page for echo is actually for a wrong echo on my Linux Mint because my echo doesn't support any arguments at all, whereas the man page lists some arguments that echo purportedly supports.
Poor Usability
An additional problem of man is that you can easily search a web page, for example, with Ctrl+F, but you wouldn't know how to do this in the man pages unless you know how to use less. If you press the h key, you get help for less, but guess what? You can't search the help for less for how to search in less because you don't know how to search in less!
To be fair, at least the method to do that is around the top of the less help page.
In any case, it would be far easier to read this documentation if it was just a web page. You don't need Internet for this, you just need a web browser and an HTML file, and every modern operating system has one installed by default.
This is not an absurd proposition. Windows has had built-in help for ages in the form of essentially web pages in an off-line help viewer. If ou can open a text file in less, you already depend on the system having a text viewer, you can depend on there being a HTML viewer.
Literally Nobody Knows How to Use Man
You can use Linux for decades and not realize that a term may have MULTIPLE man pages and that man only shows you ONE page by default. More specifically, they are sections, and the way they work makes me think whoever designed this system just doesn't want people to read docs at all.
If a man page cites, for example, bootup(7), that means section 7, bootup page. You may notice that every time you type man <something> you see <something> (1) on the corner, because that's section 1. So here is the big question: how do you access bootup(7)?
Can you simply man bootup and press a key to go the next section? No. You can't. Because the manual page is being displayed by less, a completely separated program that just lets you browse arbitrary text. less doesn't even know you're reading the manual, so it has no way to provide you with a key to go to the next section.
Hyperlinks solved this problem in the 90's, by the way.
Oh well, I guess you just man bootup(7), then? The way it's cited? That makes sense and sounds intuitive! But no. That won't work.
> man bootup(7)
bash: syntax error near unexpected token `('Because it's not valid Bash. You need to know Bash in order to read the manual!
> man "bootup(7)"By the way, there is no bootup(2). There is bootup(1) and bootup(7), but no bootup(2).
You can also do:
> man 7 bootupBut who would know about this? Maybe it's in the manual for manual?
> man
What manual page do you want?
For example, try 'man man'.Yes, if you type man, it tells you to type man man, and if you type that, it actually explains there that the sections are for completely different categories of explanations, which is good because for a moment I thought they were just arbitrarily breaking the pages in sections to mess with people.
Still, this is really just poor design in general. It feels like you need to be a text adventure gamer just to figure out how the manual works. Nowadays we have much more convenient and intuitive alternatives online, but we could have it offline as well, we simply don't.
I assume much of this is due to terminal user interfaces being terrible in general, but there is a lot of room for improvement nonetheless.
I'd like to note that GNOME Terminal, for example, has a Help -> Contents in its menubar on Linux Mint, and if you click that it opens a help viewer that works like a web browser for the offline help. That's the bare minimum software needs these days.