opinion: comp lang docs style

[Emile van Sebille]

On 1/5/2011 12:10 PM rurpy at yahoo.com said...

<snip>

> A language reference manual should completely and accurately
> describe the language it documents.  (That seems fairly obvious
> to me although there will be differing opinions of how precise
> one needs to be, etc.)  Once it meets that minimum standard,
> it's quality is defined by how effectively it transfers that
> information to its target audience.  A good reference manual
> meets the learning needs of the target audience above admirably.
>
> I learned Perl (reputedly more difficult to learn than Python)
> from the Perl manpages and used it for many many years before
> I ever bought a Perl book.  I learned C mostly from Harbison
> and Steele's "C: A Reference".  Despite several attempts at
> python using its reference docs, I never got a handle on
> it until I forked out money for Beazley's book.

Hmm... I suspect most of us with prior programming experience simply 
worked the tutorial and immediately put python into play, digging deeper 
as necessary.  Further, absolute beginners at programming are not likely 
to learn programming from a man page, nor should anyone expect the 
tutorial to be sufficient for their needs.

I agree that as far as the specific details around the edges and corner 
cases go, it would be nice to have a single reference that provides 
those answers at the level you need (ala postscript's redbook imo), but 
I find this group serves well to fill the gaps when I can't easily find 
what I need.

Emile