[Novalug] Man pages

[Beartooth]

On Mon, 17 Oct 2011, Peter Larsen wrote:

> man pages are mostly for reference manuals. Not a user manual. 
> In other words, you sorta have to know a bit about what you're 
> looking at to get the details.

 	You are falling head over heels into the classic trap for 
the advanced expert. You've gotten so far that you disremember 
beginnings.

 	It's part of the human condition. What seems to you 
"sorta" and "a bit" is orders (*several* orders) of magnitude 
beyond everything I know or hope to.

> HOWEVER - every man page is divided into sections - the first 
> is a summary/overview. That should tell you what purpose a 
> given command/file has. You can refer to this without any prior 
> knowledge.

 	True in intention, dead wrong in practice. It typically 
contains half a dozen to half a hundred technical terms which 
I've never seen before.

 	Sure, I could look them up : if it starts out with the 
classic example (among linguists), "The gostak distims the 
doshes," I can go to "man gostak," and so on -- where I can be 
sure I'll hit the same problem, most likely harder.

 	Ideally, of course, I should go take a "computer ed" 
course somewhere (if one exists), akin to driver ed and hunter 
ed (neither of which I've ever had; yet I drive and hunt).

 	But programming is not yet so widespread as hunting, let 
alone driving. And will anyone maintain that man pages aren't, or 
shouldn't be, written for programmers? I sure won't.

 	Note that I'm not objecting to man pages' existence, but 
to the lack of a pons asinorum (not a royal road, just a humble 
bridge) for the uninitiated. Man pages, or something very 
similar, have to exist -- for programmers.

 	But I'm no more likely to become a programmer than a 
manufacturer of automotive vehicles or hunting arms.

 	Nor is it any programmer's job, nor part of programming, 
to write textbooks, as opposed to manuals. But if writers of 
textbooks, especially "teach yourself" type textbooks, have yet 
appeared, they are few and far between.

> And then of course you have the internet - that goes unsaid ;) 
> If you want to find an example of how a command can be used, 
> you should be able to find examples of pretty much every 
> command you come across out on the web.

 	Mark Twain said it, and it fits apropos, help, and 
google, let alone the whole Net : "Intellectual food, like any 
other, is better taken with a spoon than a shovel."

-- 
Beartooth Staffwright, Not Quite Clueless Power User
Remember I know little (precious little!) of where up is.