diff --git a/activemodel/lib/active_model/dirty.rb b/activemodel/lib/active_model/dirty.rb
index 4c80863e3a7d6c7da14e3ecd96a97d39c3df2da2..5ea7636427404cf05c6da27bbc3befa22f824d84 100644
--- a/activemodel/lib/active_model/dirty.rb
+++ b/activemodel/lib/active_model/dirty.rb
@@ -83,7 +83,10 @@ module ActiveModel
   #   person.name_changed?  # => false
   #   person.name           # => 'Bill'
   #
-  # Before modifying an attribute in-place:
+  # If an attribute is modified in-place then make use of <tt>[attribute_name]_will_change!</tt>
+  # to mark that the attribute is changing. Otherwise ActiveModel can't track changes to 
+  # in-place attributes.
+  #
   #   person.name_will_change!
   #   person.name << 'y'
   #   person.name_change    # => ['Bill', 'Billy']