From: Dave Thomas <dave@...>
Date: 2004-03-23T02:46:42+09:00
Subject: Need some advice on PickAxe II

Folks:

It's looking as if we're moving towards agreement with Addison Wesley 
on getting the rights to Programming Ruby back. This means that we'll 
be able to produce an updated version, covering Ruby 1.8. No promises: 
we still don't have all the signed agreements, but AW is certainly 
being very helpful so far.

Now... I have a question. When it came to documenting the library that 
comes with Ruby (the stuff in lib/ and ext/), the original PickAxe 
trying to document every method in a subset of the 1.6 distribution: we 
picked the library classes and modules that looked as if they were 
being used.

In Ruby 1.8, the library has grown astonishingly: I count almost 100 
library modules and classes in lib/ alone. If we were to document these 
in any kind of detail, the book would grow to 2000 pages, and we 
wouldn't be done until 2008 :)

At the same time, the ruby-doc folks are making significant inroads in 
adding documentation the library itself: this is available both through 
ri and as HTML (at ruby-doc.org, for example).

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. I've posted sample pages at

    http://www.pragmaticprogrammer.com/extracts/sl.pdf

(These are rough, and contain typesetting problems and other errors---I 
just wanted to give folks a feel for what I was talking about).

So, here's the question: is this the way to go? Are folks happy seeing 
this kind of synoptic information in the book, and then referring to 
the online or local documentation for the details? (Don't worry about 
the built-in stuff: I'm keeping the existing format for all of that, so 
you'll still have the complete method listing for String, Array, and 
friends).


Cheers

Dave