Comment by IgorPartola

8 years ago

By Linux do you mean GNU? Because those are the wordiest and least straightforward. BSDs tend to have excellent documentation as do some individual projects (git), while others (OpenSSL) leave something to be desired. And of course GNU tar is a special little hell. But Linux just happens to run on a GNU userland most of the time so you get those a lot.

5 comments

IgorPartola

Reply
jlebar  8 years ago

> BSDs tend to have excellent documentation as do some individual projects (git)

Should we really point to git as an example of great documentation? I mean, this exists and has to have a giant banner at the top saying "these are NOT REAL": https://git-man-page-generator.lokaltog.net/

  • fiddlerwoaroof  8 years ago

    Yeah, I use the git manpages all the time when I need to do something unusual and have generally found them to be very helpful, but they aren’t written for people who don’t know how to use git.

wichert  8 years ago

On many Linux systems there are likely to be more non-GNU commands than GNU commands, so I'm not sure your argument fully works here.

GNU historically never made man pages: they used Texinfo for documentation, possibly combined with a tool to convert Texinfo to man pages. That shows in the result: an entire manual all joined together in a single unreadably long manual page. The bash man page is a nice example of that. I'm not sure if the use of Texinfo is still a requirement for GNU projects.

The verbosity of the generated man pages for GNU software probably did influence a lot of non-GNU Linux software.

  • jwilk  8 years ago

    At least in bash 4.4, the manpage and the info page are two different documents.

    Many GNU manpages are generated with help2man, which causes the opposite problem, i.e. they are too terse. (Also, their typographical quality is often low.)