README.md in jbuilder-2.8.0 vs README.md in jbuilder-2.9.0

@@ -154,11 +154,10 @@
 if current_user.admin?
   json.visitors calculate_visitors(@message)
 end
 ```
 
-
 You can use partials as well. The following will render the file
 `views/comments/_comments.json.jbuilder`, and set a local variable
 `comments` with all this message's comments, which you can use inside
 the partial.
 
@@ -182,10 +181,29 @@
 # or
 
 json.comments @post.comments, partial: 'comments/comment', as: :comment
 ```
 
+The `as: :some_symbol` is used with partials. It will take care of mapping the passed in object to a variable for the partial. If the value is a collection (either implicitly or explicitly by using the `collection:` option, then each value of the collection is passed to the partial as the variable `some_symbol`. If the value is a singular object, then the object is passed to the partial as the variable `some_symbol`.
+
+Be sure not to confuse the `as:` option to mean nesting of the partial. For example:
+
+```ruby
+ # Use the default `views/comments/_comment.json.jbuilder`, putting @comment as the comment local variable.
+ # Note, `comment` attributes are "inlined".
+ json.partial! @comment, as: :comment
+```
+
+is quite different than:
+
+```ruby
+ # comment attributes are nested under a "comment" property
+json.comment do
+  json.partial! "/comments/comment.json.jbuilder", comment: @comment
+end
+```
+
 You can pass any objects into partial templates with or without `:locals` option.
 
 ```ruby
 json.partial! 'sub_template', locals: { user: user }
 
@@ -253,24 +271,9 @@
 environment.rb for example):
 
 ``` ruby
 Jbuilder.key_format camelize: :lower
 ```
-
-Faster JSON backends
---------------------
-
-Jbuilder uses MultiJson, which by default will use the JSON gem. That gem is
-currently tangled with ActiveSupport's all-Ruby `#to_json` implementation,
-which is slow (fixed in Rails >= 4.1). For faster Jbuilder rendering, you can
-specify something like the Yajl JSON generator instead. You'll need to include
-the `yajl-ruby` gem in your Gemfile and then set the following configuration
-for MultiJson:
-
-``` ruby
-require 'multi_json'
-MultiJson.use :yajl
- ```
 
 ## Contributing to Jbuilder
 
 Jbuilder is the work of many contributors. You're encouraged to submit pull requests, propose
 features and discuss issues.