Re: Need some advice on PickAxe II

Dave Thomas wrote:

> 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
> 
> 
> 

I think this is an excellent idea, what the community is particularly 
lacking in terms of documentation is examples and usage.  API info is 
important, particularly if it's an obscure section, but when I look at a 
new library I want to know what it's capable of, and that's what 
examples show.

Charles Comstock