diff --git a/activemodel/lib/active_model/serialization.rb b/activemodel/lib/active_model/serialization.rb
index f7b1880ed93e991ec166773fd31e8d9fc9760faa..51f078e6626ff2dd116633808aca876962f9adab 100644
--- a/activemodel/lib/active_model/serialization.rb
+++ b/activemodel/lib/active_model/serialization.rb
@@ -17,7 +17,7 @@ module ActiveModel
   #     attr_accessor :name
   #
   #     def attributes
-  #       {'name' => name}
+  #       {'name' => nil}
   #     end
   #
   #   end
@@ -29,8 +29,11 @@ module ActiveModel
   #   person.name = "Bob"
   #   person.serializable_hash   # => {"name"=>"Bob"}
   #
-  # You need to declare some sort of attributes hash which contains the attributes
-  # you want to serialize and their current value.
+  # You need to declare an attributes hash which contains the attributes
+  # you want to serialize. When called, serializable hash will use
+  # instance methods that match the name of the attributes hash's keys.
+  # In order to override this behavior, take a look at the private
+  # method read_attribute_for_serialization.
   #
   # Most of the time though, you will want to include the JSON or XML
   # serializations. Both of these modules automatically include the
@@ -47,7 +50,7 @@ module ActiveModel
   #     attr_accessor :name
   #
   #     def attributes
-  #       {'name' => name}
+  #       {'name' => nil}
   #     end
   #
   #   end