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