From: Gavin Sinclair <gsinclair@...>
Date: 2004-03-23T06:48:13+09:00
Subject: Re: Need some advice on PickAxe II

On Tuesday, March 23, 2004, 4:46:42 AM, Dave wrote:

> So, this is what I'm thinking. Rather than document all the methods in
> all the lib/ and ext/ classes and modules, I'd like to have a one-page
> summary for each. Each page would contain a synopsis of the function of
> the library, along with a small number of samples of use. The idea is
> that you can read through this to find libraries that would be useful,
> and then consult the RDoc for details. Think of it as a kind of 
> exhaustive library cookbook.

That's a sensible approach, but I think you should be flexible about
how much detail each library gets.

For instance, 'date' is an important class, and a reader of Pickaxe
should come away fairly expert in its usage.  'soap', on the other
hand, is much more "optional".

The differences between 'date' and 'soap' are:
 * everyone needs 'date' from time to time, but only a few need 'soap';
 * someone interested in SOAP (in general) should read a book on SOAP
   (even though it's not about Ruby), whereas for someone interested
   in 'date', Pickaxe is all they've got.

So basically, not all libraries are equal, and they shouldn't be
treated as such.  The criteria I identified are the best I can think
of, but there may be a better way to decide what gets the one-page
treatment and what gets more detail.

Layout-wise, I'd probably do a one-pager on *all* libraries in one
chapter, and then have a few themed chapters where some libraries are
explored in more detail.

HTH,
Gavin