[conspire] man pages :-), ...

[Rick Moen]

Quoting Michael Paoli (Michael.Paoli at cal.berkeley.edu):

> *What*?!?!?!?! ... ;-) ... but (semi-)seriously, man pages can be a *great*
> resource to learn from!  Uhm, okay, ... maybe relatively and appropriately
> judiciously applied - at least these days.

Edge case much?  ;->

Yes, we've all learned from man pages, and been grateful for them -- but
that merely talks around, and ignores, the larger and more-vital point,
that in general they are _terrible_ as tutorials.  (The classic use-case
for a tutorial is:  I am a complete novice at $FOO, and so want to read
a text that teaches it to me from first principles.)

Anyone who's willing to put up with the man page for GNU find, for
example, to learn how to use it from first principles, has my profound
respect, but also my concern for that person's sanity.  The point is
that there are much better places to learn.

There is a good reason why I mentioned that larger and more-vital point:
Generations of people have, to my personal knowledge, bounced off Unix
man pages and fled in terror and dismay, because they made the bad
assumption that this is a good place to learn basics from.  One of our 
most important tasks as ambassadors for the *ix community is to help
newcomers fall into such pitfalls.  This isn't just my opinion; it's a
notorious problem.

And, in that context, here _you_ are, (in essence) talking about how
wonderful the pitfall is, and how much newcomers will find it
comfortable.

This word 'ambassador', I do not think it means what you think it means.

> And yes, heck, *much* of what I taught myself regarding Unix, and later
> Linux, was from reading the man pages!  :-)  

Yes, we all did.

And, my point, there are much better places for most learning, and we
should carefully tell people about that rather than bragging about 
our heroic ascent or Mount find(1).

> Ah, ... lovely beautiful man pages - just exactly enough to precisely
> and exactly explain everything only and exactly once, in as few words
> and feasible, with not a wasted word to spare.  ;-) 

Which is exactly what makes them perfect as quick references, and
abysmal as tutorials.  If you cannot see that, then you are failing to
comprehend the difference.

If we're serious about helping people, we need to understand that
difference -- and clue newcomers into the existence of less terse, more
tutorial-like places to learn from.