In the area of learning more Ruby and teaching others about its greatness, I did some uncovering yesterday:

Shortly: RDoc is amazing.

The :include: _somefile_ statement is a powerful way of keeping your README and your code rather separate. If that is what you want, then you can put the long, descriptive story about your code in a separate file, and use the interspersed API docs comments for documenting the parts of it.

(This post was written at the 43Things.com website, and sent to the Morningstar blog using some XMLRPC. If it works, it is quite fancy.)