diff --git a/README.md b/README.md
index 4ef2748..d9cc490 100644
--- a/README.md
+++ b/README.md
@@ -12,14 +12,17 @@ Note: CouchRest only support CouchDB 0.9.0 or newer.
 
 ## Easy Install
 
-Easy Install is moving to RubyForge, heads up for the gem.
+    $ sudo gem install couchrest
+   
+Alternatively, you can install from Github:
+    
+    $ gem sources -a http://gems.github.com (you only have to do this once)
+    $ sudo gem install mattetti-couchrest
 
 ### Relax, it's RESTful
 
-The core of Couchrest is Heroku’s excellent REST Client Ruby HTTP wrapper.
-REST Client takes all the nastyness of Net::HTTP and gives is a pretty face,
-while still giving you more control than Open-URI. I recommend it anytime
-you’re interfacing with a well-defined web service.
+CouchRest rests on top of a HTTP abstraction layer using by default Heroku’s excellent REST Client Ruby HTTP wrapper.
+Other adapters can be added to support more http libraries.
 
 ### Running the Specs
 
@@ -27,7 +30,7 @@ The most complete documentation is the spec/ directory. To validate your
 CouchRest install, from the project root directory run `rake`, or `autotest`
 (requires RSpec and optionally ZenTest for autotest support).
 
-## Examples
+## Examples (CouchRest Core)
 
 Quick Start:
 
@@ -59,12 +62,50 @@ Creating and Querying Views:
       })
     puts @db.view('first/test')['rows'].inspect 
 
-## CouchRest::Model
 
-CouchRest::Model has been deprecated and replaced by CouchRest::ExtendedDocument
+## CouchRest::ExtendedDocument  
 
+CouchRest::ExtendedDocument is a DSL/ORM for CouchDB. Basically, ExtendedDocument seats on top of CouchRest Core to add the concept of Model.
+ExtendedDocument offers a lot of the usual ORM tools such as optional yet defined schema, validation, callbacks, pagination, casting and much more.
 
-## CouchRest::ExtendedDocument
+### Model example
+
+Check spec/couchrest/more and spec/fixtures/more for more examples
+
+    class Article < CouchRest::ExtendedDocument
+      use_database DB
+      unique_id :slug
+
+      view_by :date, :descending => true
+      view_by :user_id, :date
+
+      view_by :tags,
+        :map => 
+          "function(doc) {
+            if (doc['couchrest-type'] == 'Article' && doc.tags) {
+              doc.tags.forEach(function(tag){
+                emit(tag, 1);
+              });
+            }
+          }",
+        :reduce => 
+          "function(keys, values, rereduce) {
+            return sum(values);
+          }"  
+
+      property :date
+      property :slug, :read_only => true
+      property :title
+      property :tags, :cast_as => ['String']
+
+      timestamps!
+
+      save_callback :before, :generate_slug_from_title
+
+      def generate_slug_from_title
+        self['slug'] = title.downcase.gsub(/[^a-z0-9]/,'-').squeeze('-').gsub(/^\-|\-$/,'') if new_document?
+      end
+    end
 
 ### Callbacks
 
@@ -114,4 +155,11 @@ Basically, you can paginate through the articles starting by the letter a, 5 art
 Low level usage:        
 
     Article.paginate(:design_doc => 'Article', :view_name => 'by_date',
-      :per_page => 3, :page => 2, :descending => true, :key => Date.today, :include_docs => true)
\ No newline at end of file
+      :per_page => 3, :page => 2, :descending => true, :key => Date.today, :include_docs => true)
+      
+      
+## Ruby on Rails
+
+CouchRest is compatible with rails and can even be used a Rails plugin.
+However, you might be interested in the CouchRest companion rails project:
+[http://github.com/hpoydar/couchrest-rails](http://github.com/hpoydar/couchrest-rails)      
\ No newline at end of file