README.md in draper-1.2.1 vs README.md in draper-1.3.0

@@ -50,11 +50,11 @@
 design calls for a slighly different formatting to the date for a `Book`.
 
 Now your helper method can either switch based on the input class type (poor
 Ruby style), or you break it out into two methods, `book_publication_status` and
 `article_publication_status`. And keep adding methods for each publication
-type...to the global helper namespace. And remember all the names. Ick.
+type...to the global helper namespace. And you'll have to remember all the names. Ick.
 
 Ruby thrives when we use Object-Oriented style. If you didn't know Rails'
 helpers existed, you'd probably imagine that your view template could feature
 something like this:
 
@@ -107,11 +107,11 @@
 ## Installation
 
 Add Draper to your Gemfile:
 
 ```ruby
-gem 'draper', '~> 1.0'
+gem 'draper', '~> 1.3'
 ```
 
 And run `bundle install` within your app's directory.
 
 If you're upgrading from a 0.x release, the major changes are outlined [in the
@@ -129,15 +129,16 @@
 end
 ```
 
 ### Generators
 
-When you have Draper installed and generate a resource with...
+When you have Draper installed and generate a controller...
 
 ```
 rails generate resource Article
 ```
+
 ...you'll get a decorator for free!
 
 But if the `Article` model already exists, you can run...
 
 ```
@@ -147,11 +148,11 @@
 ...to create the `ArticleDecorator`.
 
 ### Accessing Helpers
 
 Normal Rails helpers are still useful for lots of tasks. Both Rails' provided
-helper and those defined in your app can be accessed via the `h` method:
+helpers and those defined in your app can be accessed within a decorator via the `h` method:
 
 ```ruby
 class ArticleDecorator < Draper::Decorator
   def emphatic
     h.content_tag(:strong, "Awesome")
@@ -165,12 +166,13 @@
 include Draper::LazyHelpers
 ```
 
 ...at the top of your decorator class - you'll mix in a bazillion methods and
 never have to type `h.` again.
-(Note: the `capture` method is only available through `h` or `helpers`)
 
+(*Note*: the `capture` method is only available through `h` or `helpers`)
+
 ### Accessing the model
 
 When writing decorator methods you'll usually need to access the wrapped model.
 While you may choose to use delegation ([covered below](#delegating-methods))
 for convenience, you can always use the `object` (or its alias `model`):
@@ -185,11 +187,11 @@
 
 ## Decorating Objects
 
 ### Single Objects
 
-Ok, so you've written a sweet decorator, now you're going to want to put it in
+Ok, so you've written a sweet decorator, now you're going to want to put it into
 action! A simple option is to call the `decorate` method on your model:
 
 ```ruby
 @article = Article.first.decorate
 ```
@@ -204,11 +206,13 @@
 @widget = ProductDecorator.decorate(Widget.first)
 ```
 
 ### Collections
 
-If you have a whole bunch of objects, you can decorate them all in one fell
+#### Decorating Individual Elements
+
+If you have a collection of objects, you can decorate them all in one fell
 swoop:
 
 ```ruby
 @articles = ArticleDecorator.decorate_collection(Article.all)
 ```
@@ -221,10 +225,12 @@
 
 *Note:* In Rails 3, the `.all` method returns an array and not a query. Thus you
 _cannot_ use the technique of `Article.all.decorate` in Rails 3. In Rails 4,
 `.all` returns a query so this techique would work fine.
 
+#### Decorating the Collection Itself
+
 If you want to add methods to your decorated collection (for example, for
 pagination), you can subclass `Draper::CollectionDecorator`:
 
 ```ruby
 # app/decorators/articles_decorator.rb
@@ -238,11 +244,11 @@
 @articles = ArticlesDecorator.new(Article.all)
 # or, equivalently
 @articles = ArticlesDecorator.decorate(Article.all)
 ```
 
-Draper decorates each item using its `decorate` method. Alternatively, you can
+Draper decorates each item by calling the `decorate` method. Alternatively, you can
 specify a decorator by overriding the collection decorator's `decorator_class`
 method, or by passing the `:with` option to the constructor.
 
 #### Using pagination
 
@@ -261,13 +267,16 @@
 The `delegate` method used here is the same as that added by [Active
 Support](http://api.rubyonrails.org/classes/Module.html#method-i-delegate),
 except that the `:to` option is not required; it defaults to `:object` when
 omitted.
 
-[will_paginate](https://github.com/mislav/will_paginate) needs you to
-`delegate :current_page, :per_page, :offset, :total_entries, :total_pages`.
+[will_paginate](https://github.com/mislav/will_paginate) needs the following delegations:
 
+```ruby
+delegate :current_page, :per_page, :offset, :total_entries, :total_pages
+```
+
 ### Decorating Associated Objects
 
 You can automatically decorate associated models when the primary model is
 decorated. Assuming an `Article` model has an associated `Author` object:
 
@@ -295,11 +304,11 @@
 
 ```ruby
 @article = ArticleDecorator.find(params[:id])
 ```
 
-### When to decorate objects
+### When to Decorate Objects
 
 Decorators are supposed to behave very much like the models they decorate, and
 for that reason it is very tempting to just decorate your objects at the start
 of your controller action and then use the decorators throughout. *Don't*.
 
@@ -367,11 +376,11 @@
 
 ```ruby
 require 'draper/test/rspec_integration'
 ```
 
-### Isolated tests
+### Isolated Tests
 
 In tests, Draper needs to build a view context to access helper methods. By
 default, it will create an `ApplicationController` and then use its view
 context. If you are speeding up your test suite by testing each component in
 isolation, you can eliminate this dependency by putting the following in your
@@ -388,11 +397,11 @@
 Draper::ViewContext.test_strategy :fast do
   include ApplicationHelper
 end
 ```
 
-#### Stubbing route helper functions
+#### Stubbing Route Helper Functions
 
 If you are writing isolated tests for Draper methods that call route helper
 methods, you can stub them instead of needing to require Rails.
 
 If you are using RSpec, minitest-rails, or the Test::Unit syntax of minitest,
@@ -474,11 +483,11 @@
 @article.body  # Returns the article's `.body`
 @article.author_name  # Returns the article's `author.name`
 @article.author_title # Returns the article's `author.title`
 ```
 
-### Adding context
+### Adding Context
 
 If you need to pass extra data to your decorators, you can use a `context` hash.
 Methods that create decorators take it as an option, for example:
 
 ```ruby
@@ -552,10 +561,10 @@
 end
 ```
 
 This is only necessary when proxying class methods.
 
-### Making models decoratable
+### Making Models Decoratable
 
 Models get their `decorate` method from the `Draper::Decoratable` module, which
 is included in `ActiveRecord::Base` and `Mongoid::Document` by default. If
 you're [using another
 ORM](https://github.com/drapergem/draper/wiki/Using-other-ORMs) (including