I still would really like to see examples of well designed open source Ruby projects that follow what you consider to be decent design principles. I think that'd make a much stronger case for your argument, and might open my eyes to something that's been in a blind spot.

Personally, I feel like a certain amount of API design is bound to what consumers will expect. We can certainly stretch and shift their tendencies, but if we fly in the face of them, our perfection in a vacuum will never be appreciated.

When I was co-authoring Pro VB 6 & XML I was always coming across topics that could be books in themselves. Database details, designing COM objects, stuff like that.

I hated the idea that a chapter would leave the reader n limbo over some key aspect, but also didn't want to book to be even larger than it was likely to be, and explaining stuff can get hard.

So there were lots of places where I simply had to point and refer the reader to some other book or resource. There's not much you can do about that other than try to be mindful of when it is the right choice.

http://macournoyer.com/blog/2010/03/01/promote-cyopl/

But for me, I didn't want to spend a ton of time and effort on marketing, and my topic was a niche within a niche at the time (I wrote the Ruport Book with Mike Milner -- ruportbook.com).

After a year or so, instead of being thousands in the black, we were hundreds in the red, even though the book sold a few hundred copies. So we just made it available at cost and closed the doors at that point.

This may be because the HTML version was available for free when we started. It may be because we set price points very low (I think our PDF was like $8), it may be because I started an LLC and wasted tons of money on absurd taxes just for keeping the doors open. It was a bunch of epic fail on the business side of things, and that at least taught me a lesson.

I talked to O'Reilly and though they were very inflexible about certain things (due dates, typesetting, etc), they were open to change pretty much everything that mattered to me, and did. As a result, my book shipped early and at a much higher quality level than I could imagine doing myself.

Of course, I could tell you stories about other publishers I either pitched ideas for, did tech editing with, or wrote chapters for that'd make your head spin. So I wouldn't say that professional publishers are good across the board, just O'Reilly pretty much let me run with my ideas and ended up being very accomodating.

This may have something to do with the fact that I blogged and wrote articles with them for a while before writing a book, and because my editor is also a friend of mine from the Ruby community. But I know folks who have pitched O'Reilly cold and had similarly positive experiences, so I don't think that's the case.

Ultimately, publishing is going to be what you make of it. Self-publishing gives you full control, but it also gives you full responsibility. I think you can make money on it if you market effectively, and I think it can be a worthwhile if you really want to do something unique.

But for me, someone who just wanted to get some ideas out there and maybe make a buck or two in the process, doing all of the work of self publishing really was horrible.

I had a mixed blessing with my first book effort, Pro VB 6 & XML. I started out as one of about 10 authors, expected to contribute one or two chapters, and ended up as one of two authors and writing a little over half the book.

I got to write about stuff I was already quite familiar with, so it went pretty quick. And the book did OK, so I made some decent money, and the time spent was well worth it.

However: It gave me the impression this was a repeatable event. :)

Aside from the odd chapter for Wrox (most of which never saw the light of day because books got canceled, though I still got paid since I was not on royalties for them), my next book effort was Beginning Ruby for Wrox, around 2001 or so.

Way more work, the tech market was turning to shit, and Ruby was still an uber-niche area. Wrox then went bankrupt, and I never saw my final check for work completed. I got, I think, a grand for several months work.

Just before Wrox burned I had some discussions with my editor who suggested various ways to monetize what I had already written. Mostly it was "have a Web site".

Thing is, there is so much free quality info already available that drumming up eyeballs and getting people to part with cash is quite tricky.

If you're thinking of writing a book you really need to have your eyes open and keep realistic expectations, and be comfortable with what you can expect. If the goal is to build a rep, then sales may not matter. But you are still competing for attention.

Greg has the Ruby Best Practices blog; I'm quite honored to be allowed to publish there (and I wish I could get my ass in gear to write more). I'd be all for having ads on the site and finding a way to get some cash back to Greg & O'Reilly so long as it didn't spoil the reader's experience.

But I think that's quite doable.

I also think E-books can do better by exploiting their E-nature. I've had some ideas for E-books that weren't simply paper books turned PDF. There is lot's you can do with them, and perhaps there are ways to hook them into a recurring revenue service (say, a subscription to Best Practices screencasts or something.)

I can't emphasize enough, though, that people who find these things valuable should see about remunerating the author. If you want to see more things like this, help out.

People like Greg deserve a lot of credit for trying things out and trying to provide quality material in an affordable way. He is one of the reasons I'm proud to be part of the Ruby community.

I'd rather start with a hash and then see if it later demands more, than start inventing objects that, based on existing use cases, need only be hashes or structs.

I'd also rather go through a number of pre-1.0 iterations to get real-world usage to shake out the painful API parts. Up until then I'm happy to break compatibility if experience says there's some bad code in there.

Monkeybars, for example, had some methods that began life using positional args, but they were changed to use hash values. I hated it.

Aside from the extra typing required for every call, with positional args I got used to reading code and seeing things in a fixed order, so when I had to use the method myself I knew exactly what needed to go where. (These methods had 2 arguments, with maybe an optional third or so.)

With the hash args the order could vary so I had to keep looking up what the possible argument key values could be.

(Thing about using hashes for args: with positional arguments you need only know what role an argument is playing in order to know what sort of value to pass in, but with a hash you have to know the exact key name. That ends up being more stuff to look up in the docs, especially if the API designer has a quirky way of naming things.)

You might think that at least for a code reader the use of hash keys would better document the call, but the method name and the names of items being passed in were almost always sufficient.

I suspect this particular change was a result of over-thinking these methods and expected usage instead of actually paying attention to what the code was doing right now, and how people were using it right now.

There are times when my gut tells me, "You know what's going to happen with this code later", and I try to take that into consideration, but (usually) simple wins for me.

    #from your book
    
    def distance(*points)
      case(points.length)
      when 2
        x1,y1,x2,y2 = points.flatten
      when 4
        x1,y1,x2,y2 = points
      else
        raise ArgumentError, "Points may be specified as [x1,y1], [x2,y2] or x1,y1,x2,y2"
      end
      Math.hypot(x2 - x1, y2 - y1)
    end

    puts distance(1, 2, 5, 6)
    puts distance([1, 2], [5, 6])

    # why would you choose to make a complicated interface that requires a complicated implementation?

    # simple, clear interfaces that allow for simple implementations
    # are almost always preferrable to complicated ones that save a
    # keystrokes through syntax

    class Point
      attr_accessor :x
      attr_accessor :y
  
      def initialize
        self.x = 0
        self.y = 0
      end
  
      def self.with(x, y)
        new.set(x, y)
      end
  
      def set(x, y)
        self.x = x
        self.y = y
        self
      end
  
      def distance_to(a_point)
        Math.hypot(a_point.x - x, a_point.y - y)
      end
    end

    puts Point.with(1, 2).distance_to(Point.with(5, 6))

It would seem you only see the surface beauty of things. [redacted -- good point]

To be clear, I think that it is great that you created this book. I just responded as I did because I'm often frustrated when I use Ruby APIs that sacrifice good design (imo) for syntactic terseness.