From: Gregory Brown Date: 2009-02-27T05:47:02+09:00 Subject: Re: Sample Chapter from "Ruby Best Practices" On Thu, Feb 26, 2009 at 3:30 PM, 7stud -- wrote: > Gregory Brown wrote: >> >> This book is aimed mostly at people with a decent technical grasp of >> Ruby but not a ton of practical experience.  The goal is to show how >> to attack Ruby problems in the way that a seasoned Rubyist might. >> > > I have just about 0 technical grasp of ruby, but so far I can understand > everything in your example chapter.  I did have to look up a few things > in pickaxe2. That's great. If you can read this chapter with a reference to dive into when you need it, then you'll have no trouble with the whole book. My disclaimer is mostly because I don't make any effort to include 'beginner ruby' content, but it may not be as difficult to approach as I make it sound for those who are willing to look things up. >> == Please help me improve the book! >> >>  I still have a few weeks to make revisions, so whether you plan on >> buying the book or not, feel free to offer some feedback. > > Ok, here goes. For the grammatical corrections, I'll make all of them. I should have put a disclaimer that this hasn't gone through O'Reilly's proofreaders yet, only the internal tech review team I set up. So the typos and bad grammar are all my fault, and will be corrected before we print, hopefully. Of course, those who have signed up for roughcuts or read this free chapter are still encouraged to point out these issues. The more I fix before I hand the draft over, the better. > 4) I found this confusing: > >>> A.new > NoMethodError: undefined method `inspect' for # > ... > Maybe IRB bug!!   <-----*** > > You use "Maybe IRB bug!!" in several places, and it doesn't add anything > explanatory to the output--quite the contrary.  I found it confusing. It's part of the actual irb output, so that's just verbatim copying, not added commentary. I agree though. Take it up with ruby-core :) > 5) I found the following example more confusing than what it was trying > to explain: > I think the parallel assignment makes it hard to track what's going on. > If the reader is such a beginner that you need to spell out how to save > a value and then later restore it, how about doing it with absolute > crystal clarity(which in my opinion can't be done with irb output): You're right... I shouldn't be expecting the reader to not have this experience. > Personally, I think the original explanation was clear enough, and this > example should be binned. So, actually... there are more than a few cases where an internal tech reviewer pointed something out, and I said "If a reader points this out, I'll make the change". This is one of them. Consider that example slashed. Thanks for the great feedback. -greg