diff --git a/actionpack/lib/action_controller/metal/mime_responds.rb b/actionpack/lib/action_controller/metal/mime_responds.rb
index 6bf306ac5b..fe6b6c2f26 100644
--- a/actionpack/lib/action_controller/metal/mime_responds.rb
+++ b/actionpack/lib/action_controller/metal/mime_responds.rb
@@ -82,7 +82,7 @@ module ActionController #:nodoc:
     # (by name) if it does not already exist, without web-services, it might look like this:
     #
     #   def create
-    #     @company = Company.find_or_create_by_name(params[:company][:name])
+    #     @company = Company.find_or_create_by(name: params[:company][:name])
     #     @person  = @company.people.create(params[:person])
     #
     #     redirect_to(person_list_url)
@@ -92,7 +92,7 @@ module ActionController #:nodoc:
     #
     #   def create
     #     company  = params[:person].delete(:company)
-    #     @company = Company.find_or_create_by_name(company[:name])
+    #     @company = Company.find_or_create_by(name: company[:name])
     #     @person  = @company.people.create(params[:person])
     #
     #     respond_to do |format|
@@ -120,7 +120,7 @@ module ActionController #:nodoc:
     # Note, however, the extra bit at the top of that action:
     #
     #   company  = params[:person].delete(:company)
-    #   @company = Company.find_or_create_by_name(company[:name])
+    #   @company = Company.find_or_create_by(name: company[:name])
     #
     # This is because the incoming XML document (if a web-service request is in process) can only contain a
     # single root-node. So, we have to rearrange things so that the request looks like this (url-encoded):
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index d8b6d7a86b..d0f5608f68 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -459,7 +459,7 @@ module ActiveRecord
     #     has_many :people do
     #       def find_or_create_by_name(name)
     #         first_name, last_name = name.split(" ", 2)
-    #         find_or_create_by_first_name_and_last_name(first_name, last_name)
+    #         find_or_create_by(first_name: first_name, last_name: last_name)
     #       end
     #     end
     #   end
@@ -474,7 +474,7 @@ module ActiveRecord
     #   module FindOrCreateByNameExtension
     #     def find_or_create_by_name(name)
     #       first_name, last_name = name.split(" ", 2)
-    #       find_or_create_by_first_name_and_last_name(first_name, last_name)
+    #       find_or_create_by(first_name: first_name, last_name: last_name)
     #     end
     #   end
     #
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
index 3d374fe9b4..0a3fdef5a5 100644
--- a/activerecord/lib/active_record/base.rb
+++ b/activerecord/lib/active_record/base.rb
@@ -179,23 +179,6 @@ module ActiveRecord #:nodoc:
   #
   #   Payment.order("created_on").find_by_amount(50)
   #
-  # The same dynamic finder style can be used to create the object if it doesn't already exist.
-  # This dynamic finder is called with <tt>find_or_create_by_</tt> and will return the object if
-  # it already exists and otherwise creates it, then returns it. Protected attributes won't be set
-  # unless they are given in a block.
-  #
-  #   # No 'Summer' tag exists
-  #   Tag.find_or_create_by_name("Summer") # equal to Tag.create(name: "Summer")
-  #
-  #   # Now the 'Summer' tag does exist
-  #   Tag.find_or_create_by_name("Summer") # equal to Tag.find_by_name("Summer")
-  #
-  #   # Now 'Bob' exist and is an 'admin'
-  #   User.find_or_create_by_name('Bob', age: 40) { |u| u.admin = true }
-  #
-  # Adding an exclamation point (!) on to the end of <tt>find_or_create_by_</tt> will
-  # raise an <tt>ActiveRecord::RecordInvalid</tt> error if the new record is invalid.
-  #
   # Use the <tt>find_or_initialize_by_</tt> finder if you want to return a new record without
   # saving it first. Protected attributes won't be set unless they are given in a block.
   #
@@ -203,14 +186,6 @@ module ActiveRecord #:nodoc:
   #   winter = Tag.find_or_initialize_by_name("Winter")
   #   winter.persisted? # false
   #
-  # To find by a subset of the attributes to be used for instantiating a new object, pass a hash instead of
-  # a list of parameters.
-  #
-  #   Tag.find_or_create_by_name(name: "rails", creator: current_user)
-  #
-  # That will either find an existing tag named "rails", or create a new one while setting the
-  # user that created it.
-  #
   # == Saving arrays, hashes, and other non-mappable objects in text columns
   #
   # Active Record can serialize any object in text columns using YAML. To do so, you must
diff --git a/guides/source/engines.md b/guides/source/engines.md
index 116a7e67cd..d5ec2658fe 100644
--- a/guides/source/engines.md
+++ b/guides/source/engines.md
@@ -531,7 +531,7 @@ before_save :set_author
 
 private
   def set_author
-    self.author = User.find_or_create_by_name(author_name)
+    self.author = User.find_or_create_by(name: author_name)
   end
 ```
 
@@ -630,7 +630,7 @@ belongs_to :author, class_name: Blorgh.user_class
 The `set_author` method also located in this class should also use this class:
 
 ```ruby
-self.author = Blorgh.user_class.constantize.find_or_create_by_name(author_name)
+self.author = Blorgh.user_class.constantize.find_or_create_by(name: author_name)
 ```
 
 To save having to call `constantize` on the `user_class` result all the time, you could instead just override the `user_class` getter method inside the `Blorgh` module in the `lib/blorgh.rb` file to always call `constantize` on the saved value before returning the result:
@@ -644,7 +644,7 @@ end
 This would then turn the above code for `set_author` into this:
 
 ```ruby
-self.author = Blorgh.user_class.find_or_create_by_name(author_name)
+self.author = Blorgh.user_class.find_or_create_by(name: author_name)
 ```
 
 Resulting in something a little shorter, and more implicit in its behaviour. The `user_class` method should always return a `Class` object.
@@ -661,7 +661,7 @@ WARNING: It's very important here to use the `String` version of the class, rath
 
 Go ahead and try to create a new post. You will see that it works exactly in the same way as before, except this time the engine is using the configuration setting in `config/initializers/blorgh.rb` to learn what the class is.
 
-There are now no strict dependencies on what the class is, only what the API for the class must be. The engine simply requires this class to define a `find_or_create_by_name` method which returns an object of that class to be associated with a post when it's created. This object, of course, should have some sort of identifier by which it can be referenced.
+There are now no strict dependencies on what the class is, only what the API for the class must be. The engine simply requires this class to define a `find_or_create_by` method which returns an object of that class to be associated with a post when it's created. This object, of course, should have some sort of identifier by which it can be referenced.
 
 #### General engine configuration
 
@@ -800,7 +800,7 @@ module Blorgh::Concerns::Models::Post
     private
 
     def set_author
-      self.author = User.find_or_create_by_name(author_name)
+      self.author = User.find_or_create_by(name: author_name)
     end
   end