diff --git a/README.md b/README.md
index 7dbbf8f..966c616 100644
--- a/README.md
+++ b/README.md
@@ -289,25 +289,46 @@ You can also specifiy a date range for queries without results:
 
 swiftype-rb 1.0.0 has been rewritten to be simpler and easier to use. However, it is not compatable with the previous version, 0.0.5.
 
-To upgrade:
+To upgrade from the old version of swiftype-rb:
 
+* If you previously used the `Swiftype` client, migrate your API calls to the `Swiftype::Client` format. 
 * If you previously used the `Swiftype::Easy` client, change `Swiftype::Easy` to `Swiftype::Client`. Almost all method calls should be the same (there are a few minor changes).
-* If you previously used the `Swiftype` client, migrate your API calls to the `Swiftype::Client` format. If you are not able to do that, lock your gem version to 0.0.5 by adding this to your Gemfile:
 
-        gem 'swiftype, '= 0.0.5'
-* If you previously used the beta swiftype-easy-rb library (which was the precursor of swiftype-rb 1.0), change `Swiftype::Easy` to `Swiftype::Client` and move your configuration from the `Swiftype::Easy` module to the `Swiftype` module. For example:
+Additionally, the result object returned by search methods (for example, the old Swiftype gem's `Engine#search` or `Swiftype::Easy#search` methods) returns results in a different way. Instead of being an array of `Swiftype::Document` objects, it will be an array of Hashes.
 
-        Swiftype:Easy.configure do |configure|
-          config.api_key = 'your_api_key'
-        end
+Code like this:
 
-  can be converted to
+    client = Swiftype::Easy.new
+    results = client.search("engine_slug", "search term")
+    results.each do |result|
+      puts result.title
+    end
 
-        Swiftype.configure do |config|
-          config.api_key = 'your_api_key'
-        end
+Should be changed to this:
 
-  or simply `Swiftype.api_key = 'your_api_key'`.
+    client = Swiftype::Client.new
+    results = client.search("engine_slug", "search term")
+    results.each do |result|
+      puts result['title']
+    end
+
+If you are not able to upgrade, lock your gem version to 0.0.5 by adding this to your Gemfile:
+
+    gem 'swiftype, '= 0.0.5'
+
+To upgrade from the beta swiftype-easy-rb library (which was the precursor of swiftype-rb 1.0), change `Swiftype::Easy` to `Swiftype::Client` and move your configuration from the `Swiftype::Easy` module to the `Swiftype` module. For example:
+
+    Swiftype:Easy.configure do |configure|
+      config.api_key = 'your_api_key'
+    end
+
+can be converted to
+
+    Swiftype.configure do |config|
+      config.api_key = 'your_api_key'
+    end
+
+or simply `Swiftype.api_key = 'your_api_key'`.
 
 ## Development