From: Charles Comstock <cc1@...>
Date: 2004-03-23T14:24:29+09:00
Subject: Re: Need some advice on PickAxe II

Lothar Scholz wrote:

> Hello Charles,
> 
> Monday, March 22, 2004, 8:14:30 PM, you wrote:
> 
> 
> 
> CC> I think this is an excellent idea, what the community is particularly
> CC> lacking in terms of documentation is examples and usage.  API info is
> CC> important, particularly if it's an obscure section, but when I look at a
> CC> new library I want to know what it's capable of, and that's what 
> CC> examples show.
> 
> And immediately followed by shaking your head because you can't find
> out what the method returns or how the error handling is done -
> okay real programmers don't need error handling as long as your
> computer has a reset button.
> 
> So both are very very necessary for a successful library.
> But it still leaves the problem that the book would be around 2000
> pages. Some publishes like to hear this. So maybe moving from AW to
> Wrox Press may be a solution :-)
> 
> 

I'm not saying we don't need the API, it just bothers me when people 
believe that an API is an acceptable way to learn the library from the 
getgo.  If the API is well documented enough to have decent tutorials in 
it then perhaps, but that is not what most of the API's I have seen 
possess, though I find java to suffer from this even worse then ruby. 
That is one thing I was REALLY impressed by python about, a number of 
there core libraries were extremely well documented in a tutorial 
fashion, which then ended in an API.  That means you find out how it 
works, how to use it, and then when you have questions on the gritty 
details you wade into the deep part.  If you just hand someone an API, I 
find it very slow to start using, and often wind up misusing the library 
the first time through.

As far as pickaxe goes, I think it should be medium length.  It could be 
a touch longer then it is now, maybe a little denser, slightly smaller 
font, etc, but no I don't want a 2000 page "How To Program In ..." book. 


Obviously there is a balance, but it's really nice to have a few 
examples as templates to expand upon.  Definitely include a examples for 
each library, and then give more specific info on some of the more 
important general purpose libraries.

Charles Comstock