README.markdown in roar-rails-0.0.7 vs README.markdown in roar-rails-0.0.8

@@ -1,19 +1,25 @@
 # roar-rails
 
 _Makes using Roar's representers in your Rails app fun._
 
+Roar is a framework for parsing and rendering REST documents. For a better overview about representers please check the [roar repository](https://github.com/apotonick/roar#roar).
+
 ## Features
 
 * Rendering with responders
 * Parsing incoming documents
 * URL helpers in representers
 * Better tests
 * Autoloading
 
 ## Rendering with #respond_with
 
+roar-rails provides a number of baked-in rendering methods.
+
+### Conventional Rendering
+
 Easily render resources using representers with the built-in responder.
 
 ```ruby
 class SingersController < ApplicationController
   include Roar::Rails::ControllerAdditions
@@ -24,26 +30,40 @@
     respond_with singer
   end
 end
 ```
 
-Need to use a representer with a different name than your model? Pass it in using the `:represent_with` option:
+The representer name will be infered from the passed model class (e.g. a `Singer` instance gets the `SingerRepresenter`). If the passed model is a collection it will be extended using a representer. The representer name will be computed from the controller name (e.g. a `SingersController` uses the `SingersRepresenter`).
 
+Need to use a representer with a different name than your model? You may always pass it in using the `:represent_with` option:
+
 ```ruby
+respond_with singers, :represent_with => MusicianCollectionRepresenter
+end
+```
+
+### Represents Configuration
+
+If you don't want to use conventions or pass representers you can configure them on the class level using `#represents`. This will also call `respond_to` for you.
+
+```ruby
 class SingersController < ApplicationController
-  include Roar::Rails::ControllerAdditions
-  respond_to :json
+  represents :json, Musician
+```
+This will use the `MusicianRepresenter` for models and `MusiciansRepresenter` for representing collections.
 
-  def show
-    singer = Musician.find_by_id(params[:id])
-    respond_with singer, :represent_with => SingerRepresenter
-  end
-end
+Note that `#represents` also allows fine-tuning.
+
+```ruby
+class SingersController < ApplicationController
+  represents :json, :entity => MusicianRepresenter, :collection => MusicianCollectionRepresenter
 ```
 
-If you don't want to write a dedicated representer for a collection of items (highly recommended, thou) but rather use a representer for each item, use the `+represent_items_with+` option.
+### Old API Support
 
+If you don't want to write a dedicated representer for a collection of items (highly recommended, thou) but rather use a representer for each item, use the `:represent_items_with` option.
+
 ```ruby
 class SingersController < ApplicationController
 
   def index
     singers = Musician.find(:all)
@@ -93,9 +113,15 @@
   extend(SingerRepresenter)
   from_json(request.body)
 ```
 
 So, `#consume!` helps you figuring out the representer module and reading the incoming document.
+
+Note that it respects settings from `#represents`. It uses the same mechanics known from `#respond_with` to choose a representer.
+
+```ruby
+consume!(singer, :represent_with => MusicianRepresenter)
+```
 
 ## URL Helpers
 
 Any URL helpers from the Rails app are automatically available in representers.