1 files changed, 12 insertions, 9 deletions
diff --git a/railties/doc/guides/source/creating_plugins/odds_and_ends.txt b/railties/doc/guides/source/creating_plugins/odds_and_ends.txt
index eb127f73ca..32da7ed7f3 100644
--- a/railties/doc/guides/source/creating_plugins/odds_and_ends.txt
+++ b/railties/doc/guides/source/creating_plugins/odds_and_ends.txt
@@ -4,27 +4,30 @@
 
 The plugin initializer script 'init.rb' is invoked via `eval` (not `require`) so it has slightly different behavior.
 
-If you reopen any classes in init.rb itself your changes will potentially be made to the wrong module.  There are 2 ways around this:
+If you reopen any classes in init.rb itself your changes will potentially be made to the wrong module.  As a rule, it's better not to open any classes in `init.rb`, and it makes the plugin more difficult to turn into a gem.
 
-The first way is to explicitly define the top-level module space for all modules and classes, like `::Hash`:
+A better alternative is to reopen the class in a different file, and require that file from `init.rb`.
+
+If you must reopen a class in `init.rb`, there are various techniques.  One way is to use `module_eval` or `class_eval`:
+
+*vendor/plugins/yaffle/init.rb*
 
 [source, ruby]
 ---------------------------------------------------
-# File: vendor/plugins/yaffle/init.rb
-
-class ::Hash
+Hash.class_eval do
   def is_a_special_hash?
     true
   end
 end
 ---------------------------------------------------
 
-OR you can use `module_eval` or `class_eval`:
+Another way is to explicitly define the top-level module space for all modules and classes, like `::Hash`:
 
----------------------------------------------------
-# File: vendor/plugins/yaffle/init.rb
+*vendor/plugins/yaffle/init.rb*
 
-Hash.class_eval do
+[source, ruby]
+---------------------------------------------------
+class ::Hash
   def is_a_special_hash?
     true
   end