8 files changed, 54 insertions, 43 deletions
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index 6a91418e1f..f1600fe458 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -410,7 +410,7 @@ class ApplicationController < ActionController::Base
   # logging out removes it.
   def current_user
     @_current_user ||= session[:current_user_id] &&
-      User.find_by_id(session[:current_user_id])
+      User.find_by(id: session[:current_user_id])
   end
 end
 ```
diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md
index d1dd231cf6..87a08e8661 100644
--- a/guides/source/action_mailer_basics.md
+++ b/guides/source/action_mailer_basics.md
@@ -216,6 +216,11 @@ Action Mailer makes it very easy to add attachments.
     attachments['filename.jpg'] = File.read('/path/to/filename.jpg')
     ```
 
+  When the `mail` method will be triggered, it will send a multipart email with
+  an attachment, properly nested with the top level being `multipart/mixed` and
+  the first part being a `multipart/alternative` containing the plain text and
+  HTML email messages.
+
 NOTE: Mail will automatically Base64 encode an attachment. If you want something
 different, encode your content and pass in the encoded content and encoding in a
 `Hash` to the `attachments` method.
@@ -451,26 +456,6 @@ with the HTML and text versions setup as different parts.
 The order of the parts getting inserted is determined by the `:parts_order`
 inside of the `ActionMailer::Base.default` method.
 
-### Sending Emails with Attachments
-
-Attachments can be added by using the `attachments` method:
-
-```ruby
-class UserMailer < ActionMailer::Base
-  def welcome_email(user)
-    @user = user
-    @url  = user_url(@user)
-    attachments['terms.pdf'] = File.read('/path/terms.pdf')
-    mail(to: @user.email,
-         subject: 'Please see the Terms and Conditions attached')
-  end
-end
-```
-
-The above will send a multipart email with an attachment, properly nested with
-the top level being `multipart/mixed` and the first part being a
-`multipart/alternative` containing the plain text and HTML email messages.
-
 ### Sending Emails with Dynamic Delivery Options
 
 If you wish to override the default delivery options (e.g. SMTP credentials)
@@ -532,7 +517,7 @@ method. Here's an example:
 ```ruby
 class UserMailer < ActionMailer::Base
   def receive(email)
-    page = Page.find_by_address(email.to.first)
+    page = Page.find_by(address: email.to.first)
     page.emails.create(
       subject: email.subject,
       body: email.body
diff --git a/guides/source/active_record_basics.md b/guides/source/active_record_basics.md
index 1f25c6ae95..d9fb20f3bf 100644
--- a/guides/source/active_record_basics.md
+++ b/guides/source/active_record_basics.md
@@ -253,7 +253,7 @@ user = User.first
 
 ```ruby
 # return the first user named David
-david = User.find_by_name('David')
+david = User.find_by(name: 'David')
 ```
 
 ```ruby
@@ -270,7 +270,7 @@ Once an Active Record object has been retrieved, its attributes can be modified
 and it can be saved to the database.
 
 ```ruby
-user = User.find_by_name('David')
+user = User.find_by(name: 'David')
 user.name = 'Dave'
 user.save
 ```
@@ -279,7 +279,7 @@ A shorthand for this is to use a hash mapping attribute names to the desired
 value, like so:
 
 ```ruby
-user = User.find_by_name('David')
+user = User.find_by(name: 'David')
 user.update(name: 'Dave')
 ```
 
@@ -297,7 +297,7 @@ Likewise, once retrieved an Active Record object can be destroyed which removes
 it from the database.
 
 ```ruby
-user = User.find_by_name('David')
+user = User.find_by(name: 'David')
 user.destroy
 ```
 
diff --git a/guides/source/active_record_callbacks.md b/guides/source/active_record_callbacks.md
index bb42fab101..01401cc340 100644
--- a/guides/source/active_record_callbacks.md
+++ b/guides/source/active_record_callbacks.md
@@ -167,6 +167,7 @@ Additionally, the `after_find` callback is triggered by the following finder met
 * `all`
 * `first`
 * `find`
+* `find_by`
 * `find_by_*`
 * `find_by_*!`
 * `find_by_sql`
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index c0e584a1c7..884aa6a9ea 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -2171,7 +2171,7 @@ You're not limited to the functionality that Rails automatically builds into ass
 class Customer < ActiveRecord::Base
   has_many :orders do
     def find_by_order_prefix(order_number)
-      find_by_region_id(order_number[0..2])
+      find_by(region_id: order_number[0..2])
     end
   end
 end
diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md
index 2574a2c111..26360e815b 100644
--- a/guides/source/getting_started.md
+++ b/guides/source/getting_started.md
@@ -612,11 +612,16 @@ we want to accept in our controllers. In this case, we want to allow the
 look like this:
 
 ```
-  def create
-    @post = Post.new(params[:post].permit(:title, :text))
+def create
+  @post = Post.new(post_params)
 
-    @post.save
-    redirect_to @post
+  @post.save
+  redirect_to @post
+end
+
+private
+  def post_params
+    params.require(:post).permit(:title, :text)
   end
 ```
 
@@ -767,7 +772,7 @@ def new
 end
 
 def create
-  @post = Post.new(params[:post].permit(:title, :text))
+  @post = Post.new(post_params)
 
   if @post.save
     redirect_to @post
@@ -775,6 +780,11 @@ def create
     render 'new'
   end
 end
+
+private
+  def post_params
+    params.require(:post).permit(:title, :text)
+  end
 ```
 
 The `new` action is now creating a new instance variable called `@post`, and
@@ -905,12 +915,17 @@ Next we need to create the `update` action in `app/controllers/posts_controller.
 def update
   @post = Post.find(params[:id])
 
-  if @post.update(params[:post].permit(:title, :text))
+  if @post.update(post_params)
     redirect_to @post
   else
     render 'edit'
   end
 end
+
+private
+  def post_params
+    params.require(:post).permit(:title, :text)
+  end
 ```
 
 The new method, `update`, is used when you want to update a record
@@ -918,6 +933,8 @@ that already exists, and it accepts a hash containing the attributes
 that you want to update. As before, if there was an error updating the
 post we want to show the form back to the user.
 
+We reuse the `post_params` method that we defined earlier for the create action.
+
 TIP: You don't need to pass all attributes to `update`. For
 example, if you'd call `@post.update(title: 'A new title')`
 Rails would only update the `title` attribute, leaving all other
@@ -1062,7 +1079,7 @@ You can call `destroy` on Active Record objects when you want to delete
 them from the database. Note that we don't need to add a view for this
 action since we're redirecting to the `index` action.
 
-Finally, add a 'destroy' link to your `index` action template
+Finally, add a 'Destroy' link to your `index` action template
 (`app/views/posts/index.html.erb`) to wrap everything
 together.
 
@@ -1088,8 +1105,8 @@ together.
 </table>
 ```
 
-Here we're using `link_to` in a different way. We pass the named route as the first argument,
-and then the final two keys as another argument. The `:method` and `:'data-confirm'`
+Here we're using `link_to` in a different way. We pass the named route as the second argument,
+and then the options as another argument. The `:method` and `:'data-confirm'`
 options are used as HTML5 attributes so that when the link is clicked,
 Rails will first show a confirm dialog to the user, and then submit the link with method `delete`.
 This is done via the JavaScript file `jquery_ujs` which is automatically included
@@ -1303,9 +1320,14 @@ Let's wire up the `create` in `app/controllers/comments_controller.rb`:
 class CommentsController < ApplicationController
   def create
     @post = Post.find(params[:post_id])
-    @comment = @post.comments.create(params[:comment].permit(:commenter, :body))
+    @comment = @post.comments.create(comment_params)
     redirect_to post_path(@post)
   end
+
+  private
+    def comment_params
+      params.require(:comment).permit(:commenter, :body)
+    end
 end
 ```
 
@@ -1527,10 +1549,9 @@ controller (`app/controllers/comments_controller.rb`):
 
 ```ruby
 class CommentsController < ApplicationController
-
   def create
     @post = Post.find(params[:post_id])
-    @comment = @post.comments.create(params[:comment])
+    @comment = @post.comments.create(comment_params)
     redirect_to post_path(@post)
   end
 
@@ -1541,6 +1562,10 @@ class CommentsController < ApplicationController
     redirect_to post_path(@post)
   end
 
+  private
+    def comment_params
+      params.require(:comment).permit(:commenter, :body)
+    end
 end
 ```
 
diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md
index f6cac997ff..5908801bc9 100644
--- a/guides/source/layouts_and_rendering.md
+++ b/guides/source/layouts_and_rendering.md
@@ -592,7 +592,7 @@ def index
 end
 
 def show
-  @book = Book.find_by_id(params[:id])
+  @book = Book.find_by(id: params[:id])
   if @book.nil?
     render action: "index"
   end
@@ -607,7 +607,7 @@ def index
 end
 
 def show
-  @book = Book.find_by_id(params[:id])
+  @book = Book.find_by(id: params[:id])
   if @book.nil?
     redirect_to action: :index
   end
@@ -626,7 +626,7 @@ def index
 end
 
 def show
-  @book = Book.find_by_id(params[:id])
+  @book = Book.find_by(id: params[:id])
   if @book.nil?
     @books = Book.all
     flash.now[:alert] = "Your book was not found"
diff --git a/guides/source/migrations.md b/guides/source/migrations.md
index 508e52a77c..035f9499de 100644
--- a/guides/source/migrations.md
+++ b/guides/source/migrations.md
@@ -314,7 +314,7 @@ will produce a migration that looks like this
 class AddDetailsToProducts < ActiveRecord::Migration
   def change
     add_column :products, :price, precision: 5, scale: 2
-    add_reference :products, :user, polymorphic: true, index: true
+    add_reference :products, :supplier, polymorphic: true, index: true
   end
 end
 ```