Merge pull request chef#2976 from pburkholder/pdb/gem_warn

Clarify warning

lib/chef/provider/package/rubygems.rb

@@ -380,8 +380,13 @@ def initialize(new_resource, run_context=nil)
             # Opscode Omnibus - The ruby that ships inside omnibus is only used for Chef
             # Default to installing somewhere more functional
             if new_resource.options && new_resource.options.kind_of?(Hash)
-              msg = "options should be a string instead of a hash\n"
-              msg << "in #{new_resource} from #{new_resource.source_line}"
+              msg = [
+                "Gem options must be passed to gem_package as a string instead of a hash when",
+                "using this installation of Chef because it runs with its own packaged Ruby. A hash",
+                "may only be used when installing a gem to the same Ruby installation that Chef is",
+                "running under.  See https://docs.chef.io/resource_gem_package.html for more information.",
+                "Error raised at #{new_resource} from #{new_resource.source_line}",
+              ].join("\n")
               raise ArgumentError, msg
             end
             gem_location = find_gem_by_path