A. The dropping of full API documentation in favor of terse cookbook
pages.
(I far prefer electronic API references anyhow…easier to search,
hyperlink, and copy/paste)
B. The concept that some libraries are more important than others, and
hence should have more information devoted to them, and
C. A presentation of them in the manner Gavin S. suggests – a full
chapter of one-library-per-page, and then other chapters which contain
more in-depth coverage for those libraries necessitating careful
examination.
···
On Mar 22, 2004, at 2:48 PM, Gavin Sinclair wrote:
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.
I’m thinking on having an appendix on packaging with RubyGems - do
folks think that’s the way to go?
Cheers
Dave
···
On Mar 26, 2004, at 10:14, Piergiuliano Bossi wrote:
My 2 cents (slightly related to libs): what do you think about a new
section on installation structure, explaining rationale, usage, etc of
main directories, how to install, how to shape a library in order to
install it properly and so on?
Wrote “Zachary P. Landau” kapheine@hypa.net, on Tue, Mar 23, 2004 at 03:21:04AM +0900:
In its place, if you put a chapter on racc, on rexml, on webrick, on
soap4r, etc., tutorial style stuff on how to do useful things, that’s
the kind of thing that I don’t know will get done in the std lib
documentation, and I would be happy to buy and be able to read on my
couch, whereas it looks like the doc team (yeah team!) are doing good
work in getting the per-API docs in better shape.
I’m not sure I agree with this. Programming Ruby fits very well as an
introduction (and then reference) to the language itself. I think having
in-depth examples of how to use libraries is a job for another book
But Programming Ruby V1 already has chapters such as I suggest!
ch 14, ruby and the web (covers CGI and eruby, and integration in Apache)
ch 15, ruby tk
ch 16, ruby and windows (WIN32OLE, …)
So both are very very necessary for a successful library.
But it still leaves the problem that the book would be around 2000
pages. Some publishes like to hear this. So maybe moving from AW to
Wrox Press may be a solution
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.
And immediately followed by shaking your head because you can’t find
out what the method returns or how the error handling is done -
okay real programmers don’t need error handling as long as your
computer has a reset button.
So both are very very necessary for a successful library.
But it still leaves the problem that the book would be around 2000
pages. Some publishes like to hear this. So maybe moving from AW to
Wrox Press may be a solution
I’m not saying we don’t need the API, it just bothers me when people
believe that an API is an acceptable way to learn the library from the
getgo. If the API is well documented enough to have decent tutorials in
it then perhaps, but that is not what most of the API’s I have seen
possess, though I find java to suffer from this even worse then ruby.
That is one thing I was REALLY impressed by python about, a number of
there core libraries were extremely well documented in a tutorial
fashion, which then ended in an API. That means you find out how it
works, how to use it, and then when you have questions on the gritty
details you wade into the deep part. If you just hand someone an API, I
find it very slow to start using, and often wind up misusing the library
the first time through.
As far as pickaxe goes, I think it should be medium length. It could be
a touch longer then it is now, maybe a little denser, slightly smaller
font, etc, but no I don’t want a 2000 page “How To Program In …” book.
Obviously there is a balance, but it’s really nice to have a few
examples as templates to expand upon. Definitely include a examples for
each library, and then give more specific info on some of the more
important general purpose libraries.
Personally, I never pull out the pickaxe as a reference. I think its
real strength (and you and Andy’s core strength as a unit) is to help
people understand the high level concepts that are important when
learning a dynamic language like Ruby. To me, the biggest bang for
the buck would be for you to stay at that level, and leave API
documentation to the ruby-doc folks (which could, in this open source
community, theoretically be any/all of us).
I guess I’m just the opposite… the number one thing I’ve used my
Pickaxe for is an API reference. I like having a dead tree form I can
thumb through looking for what I want, and the Pickaxe goes everywhere
with me in my backpack. The second most useful part to me has been the
language reference - when learning Ruby it seemed like I found
something new and cool about the syntax in there every other day. I
personally picked up the high level concepts of a dynamic language
mostly elsewhere, both before and after discovering Ruby. Different
strokes for different folks, I guess.
I would side with Chad on this one – I don’t use it for an API reference.
There are many different styles of books that serve different purposes,
tutorial, task oriented, detailed reference, etc. It would be a mistake to
try to cover all of these in one book.
To build on current strengths, to minimize overlap and maximize the use of
the talents of the Ruby community here’s how I would like to see things
progress:
Tutorial – Pick Axe
Task-Oriented – The Ruby Way
Detailed Reference – The ruby-doc web site
Curt
···
On Mar 23, 2004, at 05:57, Chad Fowler wrote:
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.610 / Virus Database: 390 - Release Date: 3/3/2004
Oh, and mostly unrelated: I hope this edition uses under_score notation
instead of camelCase. I know I was led astray by the Pickaxe in my
early days of Ruby programming :-/
I avoid libraries which uses camelCase, luckily many of them
provide underscore aliases. Thus it would be really nice if Ruby2 enforced
underscores for varnames + methodnames. I know this may be a religious
subject…
Maybe I should submit an RCR… opinions/flames/benefits/drawbacks ?
···
On Tue, 23 Mar 2004 22:41:56 +0900, Nathaniel Talbott wrote:
Anyhow, I like the general direction Dave’s pointing out for this
edition, because there’s a lot of good stuff in the standard library
that folks don’t even know about, but it would be overkill to
comprehensively document all of it in the same book. OTOH, I’d love it
if some of the most useful, general purpose libraries had good,
comprehensive API documentation in the style of the original Pickaxe.
Things like WEBrick, Test::Unit, DRb, optparse, etc., that mailing
list traffic show are being used on a regular basis.
The new version has an entire chapter on Test::Unit
Oh, and mostly unrelated: I hope this edition uses under_score
notation instead of camelCase. I know I was led astray by the Pickaxe
in my early days of Ruby programming :-/
Yup - I spend a wonderful couple of days going through and changing
these. We guessed, but we got it wrong
Cheers
Dave
···
On Mar 23, 2004, at 7:41, Nathaniel Talbott wrote:
My thought would be the best approach would be, after the initial
language definitions and discussions, to take a series of common
tasks, and show how to do them. A good addition would be a
cross-index of task and class, but that might be quite difficult, as
people describe the tasks so differently.
I see that as the role of books such as The Ruby Way and the Developers
Guide. The Pickaxe is really intended to be a guide to Ruby, The
Language. We mention other major libraries briefly, but not in the kind
of depth that other go into. Again, it’s a question of space and
pagecount.
P.S.: You seem to have settled on FOX as the display kit, so I don’t
know if what I was suggesting is practical. As usual, a discussion of
alternatives, and why you are choosing the direction you are choosing
is helpful.
I’m not sure where that impression came from: as it stands right now
I’ve actually removed the Tk chapter from the book. The Ruby GUI
picture is frankly something os a mess, and I didn’t want to go there.
I’d welcome advice here.
hello Dave
I think it is ok to remove the GUI stuff.
one could write a whole or oven several books only about Ruby GUI.
so I’d rather see stuff expanded like performance, continuations
and other stuff.
markus
···
On Mar 23, 2004, at 1:40, Charles Hixson wrote:
P.P.S: Is Ruby2 in the offing? I seem to recall publishers as having
slow turn arounds…so perhaps you had better be covering that, though
whether as a “soon to appear” or as the standard version I don’t know.
The publisher we’re using has the fastest turnaround in the industry…
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
Personally, I never pull out the pickaxe as a reference. I think its
real strength (and you and Andy’s core strength as a unit) is to help
people understand the high level concepts that are important when
learning a dynamic language like Ruby. To me, the biggest bang for
the buck would be for you to stay at that level, and leave API
documentation to the ruby-doc folks (which could, in this open source
community, theoretically be any/all of us).
I guess I’m just the opposite… the number one thing I’ve used my
Pickaxe for is an API reference. I like having a dead tree form I can
thumb through looking for what I want, and the Pickaxe goes everywhere
with me in my backpack. The second most useful part to me has been the
language reference - when learning Ruby it seemed like I found
something new and cool about the syntax in there every other day. I
personally picked up the high level concepts of a dynamic language
mostly elsewhere, both before and after discovering Ruby. Different
strokes for different folks, I guess.
I’d just like to second Nathaniel’s opinion. I also carry the Pickaxe in
my backpack/briefcase and use it as a reference both at home and at work.
Anyhow, I like the general direction Dave’s pointing out for this
edition, because there’s a lot of good stuff in the standard library
that folks don’t even know about, but it would be overkill to
comprehensively document all of it in the same book.
Yeah, and it would make it difficult to carry in our backpacks.
OTOH, I’d love it
if some of the most useful, general purpose libraries had good,
comprehensive API documentation in the style of the original Pickaxe.
Things like WEBrick, Test::Unit, DRb, optparse, etc., that mailing list
traffic show are being used on a regular basis.
I’d have to agree with the list you have here. Perhaps it would be
interesting to analyze the questions that people have been asking on
c.l.r/ruby-talk to figure out which libraries to cover in-depth. I for
one would certainly like to see in-depth coverage of the ones you mention
above, though I can’t think of any others right now off the top of my
head (and maybe that’s a good thing) except for maybe REXML and syck/YAML.
But then again, maybe some of these things are best covered by examples.
Excellent (almost) news on the future of Pick Axe!
My current one is looking really abused… it’s about time to get a new
one to beat up in my backpack
Yep, I don’t think mine will last much more than another year. I hope
the new one’s out before my current one totally falls apart.
I don’t say it’s your fault I just feel that there is no single and
consistent documentation standard for ruby. Although there is ruby-doc.org
IMHO there should be a complete online reference shipped with each
installation. Or am I missing something?
You should, at some point, be able to run rdoc on the full source code
and get the same API docs as you would find on ruby-doc.org (modulo
recent updates to the latest CVS)
I believe there have been discussions (on ruby-core?) on whether this
should happen by default as part of the installation process, or if it
should be a deliberately chosen option (something like --with-rdoc or
whatever).
I’d argue for installing docs by default.
Yep. I’l get in contact with Corinna and let you know the outcome.
My 2 cents (slightly related to libs): what do you think about a new
section on installation structure, explaining rationale, usage, etc of
main directories, how to install, how to shape a library in order to
install it properly and so on?
I’m thinking on having an appendix on packaging with RubyGems - do
folks think that’s the way to go?
That probably is the way to go. At this point RubyGems seems to be
emerging as the standard packaging system (and if you put it in your book
it will definately become the standard). They still have some work to do,
however (C extensions) - when do you think you’ll be publishing? You
might want to write this part last so that RubyGems has a bit more time to
mature… or I suppose you could decide how you would like some of the
missing features to function, write them up that way and then the RubyGems
folks would have to implement them that way (Documentation-driven
development)
Oh yes, don’t get me wrong, they would definitely be nice to have. But
if I had to choose one over the other, I’d choose having an entire list
of what is available as opposed to cutting out that section in order to
provide a couple chapters on how to use specific libraries.
I wouldn’t mind paying an extra $10 or however much for a few more
chapters that go into detail. But if this isn’t a choice, I choose a
for Programming Ruby 1.8 to lean towards a reference.
···
On Tue, Mar 23, 2004 at 03:41:59AM +0900, Sam Roberts wrote:
Wrote “Zachary P. Landau” kapheine@hypa.net, on Tue, Mar 23, 2004 at 03:21:04AM +0900:
In its place, if you put a chapter on racc, on rexml, on webrick, on
soap4r, etc., tutorial style stuff on how to do useful things, that’s
the kind of thing that I don’t know will get done in the std lib
documentation, and I would be happy to buy and be able to read on my
couch, whereas it looks like the doc team (yeah team!) are doing good
work in getting the per-API docs in better shape.
I’m not sure I agree with this. Programming Ruby fits very well as an
introduction (and then reference) to the language itself. I think having
in-depth examples of how to use libraries is a job for another book
But Programming Ruby V1 already has chapters such as I suggest!
ch 14, ruby and the web (covers CGI and eruby, and integration in Apache)
ch 15, ruby tk
ch 16, ruby and windows (WIN32OLE, …)
So both are very very necessary for a successful library.
But it still leaves the problem that the book would be around 2000
pages. Some publishes like to hear this. So maybe moving from AW to
Wrox Press may be a solution
Wrox went bankrupt over a year ago.
Don’t tell me that! I was going to buy them as soon as I sold
all my Enron stock…
Seriously, I won’t miss Wrox much. Their quality was never that high.
I had fun marking up one of their last books, though.
well, we should ho the way a language for the OZ platform do (can’t
remember what)… just make any name, Name, N_A_M_E equivalent and
kill this debates for ever
Seriously, it would be nice to have some kind of Style Guidelines
somewhere (like using CamelCase for classes and under_scores for
methods, provide block form for accessing resource that need to be
freed and so on)
···
il Tue, 23 Mar 2004 14:53:59 +0100, Simon Strandgaard neoneye@adslhome.dk ha scritto::
On Tue, 23 Mar 2004 22:41:56 +0900, Nathaniel Talbott wrote:
[snip]
Oh, and mostly unrelated: I hope this edition uses under_score notation
instead of camelCase. I know I was led astray by the Pickaxe in my
early days of Ruby programming :-/
I avoid libraries which uses camelCase, luckily many of them
provide underscore aliases. Thus it would be really nice if Ruby2 enforced
underscores for varnames + methodnames. I know this may be a religious
subject…
Maybe I should submit an RCR… opinions/flames/benefits/drawbacks ?
I’m not saying we don’t need the API, it just bothers me when people
believe that an API is an acceptable way to learn the library from the
getgo. If the API is well documented enough to have decent tutorials in
it then perhaps, but that is not what most of the API’s I have seen
possess, though I find java to suffer from this even worse then ruby.
<thePennyDrops>Oh, of course!</thePennyDrops> Unit-test libraries
within the libraries themselves, as if in Extreme Programming fashion!
This will document the API with examples, and gift us with more ways
I avoid libraries which uses camelCase, luckily many of them
provide underscore aliases. Thus it would be really nice if Ruby2 enforced
underscores for varnames + methodnames. I know this may be a religious
subject…
Trying to understand your religion here. If both methods and variables
are named with underscores, not camel case how do you distinguish beween
a method that instructs something to read a certain number, and a
variable which keeps track of how many times something was read.
read_number vs. read_number.
If you name the method “readNumber” it is clear that it’s a method, and
that “read_number” is the variable. That’s why I think
camelCaseWithLeadingLowercase is better for methods.
Anyhow, I like the general direction Dave’s pointing out for this
edition, because there’s a lot of good stuff in the standard library
that folks don’t even know about, but it would be overkill to
comprehensively document all of it in the same book.
Yeah, and it would make it difficult to carry in our backpacks.
Youngsters these days… In my day, I carried multiple boxes of punch
cards in my backpack. Not to mention loading operating systems from paper
tape – at 10 cps!
OTOH, I’d love it
if some of the most useful, general purpose libraries had good,
comprehensive API documentation in the style of the original Pickaxe.
Things like WEBrick, Test::Unit, DRb, optparse, etc., that mailing list
traffic show are being used on a regular basis.
I’d have to agree with the list you have here. Perhaps it would be
interesting to analyze the questions that people have been asking on
c.l.r/ruby-talk to figure out which libraries to cover in-depth. I for
one would certainly like to see in-depth coverage of the ones you mention
above, though I can’t think of any others right now off the top of my
head (and maybe that’s a good thing) except for maybe REXML and syck/YAML.
But then again, maybe some of these things are best covered by examples.
Trying to find out what libraries exist and how to use them is a real
problem, not just in Ruby. While my assembly language programming skills
are probably better than most of the folks on this list, my Ruby
programming skills are much weaker than the average person on this list.
And, having met the authors of some of the books, I would have to say that
they are so much more skillful that I think they sometimes have trouble
talking down to my level. All in all, I think Ruby has some issues with
not being easily accessable to the non-wizard types.
I use the reference in the back of the Pickaxe book A LOT. I’d love to
see all of the included libraries documented in a similar format and
made available in a form that I could print out and have spiral bound.
Yep, I don’t think mine will last much more than another year. I hope
the new one’s out before my current one totally falls apart.
Well, while I’d like to see a 1.8 version of the book, I think it might be
better to wait for Ruby 2.0.
– Matt
Attitude: The difference between ordeal and adventure
