README.md in dbx-api-0.1.1 vs README.md in dbx-api-0.2.0

@@ -2,11 +2,14 @@
 
 ## Overview
 This gem is designed to allow access to the DBX APIs (Jobs and SQL) from ruby applications.
 
 ## Installation
-TODO: write this section
+Add the following to your Gemfile to install
+```ruby
+gem 'dbx-api', '~>0.2.0'
+```
 
 ## Usage
 Set up your .env file (optional)
 ```bash
 # .env
@@ -23,19 +26,71 @@
 sql_runner = DatabricksGateway.new
 # If not using .env file...
 sql_runner = DatabricksGateway.new(host: 'DBX_CONNECTION_STRING', token: 'DBX_ACCESS_TOKEN', warehouse: 'DBX_SQL_WAREHOUSE_ID')
 
 # Basic sql
-result = sql_runner.run_sql("SELECT 1")
-sql_runner.parse_result(result)
+response = sql_runner.run_sql("SELECT 1")
+response.results
 # => [{"1"=>"1"}]
 
 # Dummy data in public DBX table
-result = sql_runner.run_sql("SELECT * FROM samples.nyctaxi.trips LIMIT 1")
-sql_runner.parse_result(result)
+response = sql_runner.run_sql("SELECT * FROM samples.nyctaxi.trips LIMIT 1")
+response.results
 # => [{"tpep_pickup_datetime"=>"2016-02-14T16:52:13.000Z",
 #   "tpep_dropoff_datetime"=>"2016-02-14T17:16:04.000Z",
 #   "trip_distance"=>"4.94",
 #   "fare_amount"=>"19.0",
 #   "pickup_zip"=>"10282",
 #   "dropoff_zip"=>"10171"}]
-```
+```
+
+`run_sql` returns an object of type DatabricksSQLResponse.
+
+The response object has a few useful methods. For a complete list, see the class definition: `lib/dbx/databricks/sql_response.rb`
+```ruby
+response = sql_runner.run_sql("SELECT 1")
+
+# checking the status of a response
+response.status # => SUCCEEDED | FAILED | PENDING | RUNNING
+response.failed? # => Boolean
+response.success? # => Boolean
+
+# getting the results of a response
+response.results # => Array of Hashes
+
+# looking at the raw response
+response.raw_response # => HTTP object
+# or just the parsed body of the HTTP response
+response.body
+
+# checking error messages for failed responses
+response.error_message # => String
+```
+
+This gem does not make an inference to how error handling should occur. `run_sql` always returns an array, even if the query fails (it will return `[]` if status.failed?). Users may wish to check the status of the response before attempting to access the results. For example:
+```ruby
+require 'dbx'
+
+sql_runner = DatabricksGateway.new
+res = sql_runner.run_sql("SELECT 1")
+
+# do something with the results if the query succeeded
+return res.results if res.success?
+
+# do something else if the query failed
+puts "query failed: #{res.error_message}"
+```
+
+Since `run_sql` returns an instance of `DatabricksSQLResponse`, you can also chain methods together:
+```ruby
+sql_runner.run_sql("SELECT 1").results
+```
+
+## Development
+- After checking out the repo, run `bin/setup` to install dependencies. 
+- Set up your `.env` file as described above. 
+- Run `rake spec` to run the rspec tests.
+
+## Build
+- Run `gem build dbx.gemspec ` to build the gem.
+- Run `gem push dbx-api-0.2.0.gem` to push the gem to rubygems.org
+  - Requires logging in to rubygems.org first via `gem login`
\ No newline at end of file