3 ms·

gnu is in many ways wonderful but documentation is not one of the ways. gnu's two docs challenges are (1) document the command-line flags for users and (2) docu

gnu is in many ways wonderful but documentation is not one of the ways. gnu's two docs challenges are (1) document the command-line flags for users and (2) document the code for contributing devs. I've never faced case 2 but wading through man pages for case 1 is less than awesome. I agree that docs should answer the user's typical questions but gnu docs seldom do. Can you imagine trying to figure out gnu tar from the man page? You never would. Doesn't help that search engines starting with G view queries like 'tail -f' as stopwords.

bpchaps 11y ago
I dunno, I find them much better than most of the documentation I've worked with. I agree with you for beginners, since when I first started reading man pages and such, I wanted to rip my eyes out. But after a while, once I learned why the documentation was written the way it was, the flow of it started to make more and more sense. Though, in a lot of ways this comes from personal opinions that gnu tools and by extension, gnu/linux, should be difficult in the worse-is-better sense. These days, when looking at documentation, my go-to example for awful documentation is salt. Because, well, this is utter bullshit: $ man salt 2>/dev/null | wc -l 133324
- catnaroek 11y ago
  I find GNU info more useful than man pages as documentation for those who are learning how to use a program. The documentation is structured and hyperlinked in a very convenient way. On the other hand, the terseness of man pages is more convenient for those who already mostly know the program, but need a reminder of minor details like the exact command line flag to enable a specific program option.
  - bpchaps 11y ago
    Agreed, but unfortunately info is used so infrequently that I don't even bother with it these days.
  - jandrese 11y ago
    95% of the time when I'm opening a manpage I am looking for a particular command line option or syntax. With man pages I just hit / and then a relevant keyword and it jumps to the right section. With info pages I have to grok which section it might be in, then remember what arcane ctrl sequence follows links and then what sequence searches in the document then which sequence goes back because I guessed wrong. I find manpages to be much more convienent, even though they are less structured.

bpchaps 11y ago

I dunno, I find them much better than most of the documentation I've worked with. I agree with you for beginners, since when I first started reading man pages and such, I wanted to rip my eyes out. But after a while, once I learned why the documentation was written the way it was, the flow of it started to make more and more sense. Though, in a lot of ways this comes from personal opinions that gnu tools and by extension, gnu/linux, should be difficult in the worse-is-better sense. These days, when looking at documentation, my go-to example for awful documentation is salt. Because, well, this is utter bullshit: $ man salt 2>/dev/null | wc -l 133324

catnaroek 11y ago
I find GNU info more useful than man pages as documentation for those who are learning how to use a program. The documentation is structured and hyperlinked in a very convenient way. On the other hand, the terseness of man pages is more convenient for those who already mostly know the program, but need a reminder of minor details like the exact command line flag to enable a specific program option.
- bpchaps 11y ago
  Agreed, but unfortunately info is used so infrequently that I don't even bother with it these days.
- jandrese 11y ago
  95% of the time when I'm opening a manpage I am looking for a particular command line option or syntax. With man pages I just hit / and then a relevant keyword and it jumps to the right section. With info pages I have to grok which section it might be in, then remember what arcane ctrl sequence follows links and then what sequence searches in the document then which sequence goes back because I guessed wrong. I find manpages to be much more convienent, even though they are less structured.