Having one page summaries of each library seems to be a useful way to
preview, see what is of interest in order to go elsewhere to dig
deeper.  I would like to see that approach taken.

Dave Thomas <dave / pragprog.com> wrote in message news:<DFB1150A-7C28-11D8-AA8B-000A95676A62 / pragprog.com>...
> 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