GETTING_STARTED.md in recurly-3.0.0 vs GETTING_STARTED.md in recurly-3.1.0

@@ -1,30 +1,23 @@
-# Recurly
+This repository houses the official ruby client for Recurly's V3 API.
 
-## Getting Started
+# Installing
 
-### Installing
-
 In your Gemfile, add `recurly` as a dependency.
 
 ```ruby
-gem 'recurly', '~> 3.0'
+gem 'recurly', '~> 3.1'
 ```
 
 > *Note*: We try to follow [semantic versioning](https://semver.org/) and will only apply breaking changes to major versions.
 
-### Creating a client
+# Creating a client
 
-Client instances are now explicitly created and referenced as opposed to V2's use of global, statically
-initialized clients.
+A client represents a connection to the Recurly servers. Every call
+to the server exists as a method on this class. To initialize, you only need the private API key
+which can be obtained on the [API Credentials Page](https://app.recurly.com/go/integrations/api_keys).
 
-This makes multithreaded environments simpler and provides one location where every
-operation can be found (rather than having them spread out among classes).
-
-`Recurly::Client#new` initializes a new client. It only requires an API key which can be obtained on
-the [API Credentials Page](https://app.recurly.com/go/integrations/api_keys).
-
 ```ruby
 API_KEY = '83749879bbde395b5fe0cc1a5abf8e5'
 client = Recurly::Client.new(api_key: API_KEY)
 sub = client.get_subscription(subscription_id: 'abcd123456')
 ```
@@ -46,18 +39,18 @@
 # you should create a new client to connect to another site
 client = Recurly::Client.new(api_key: API_KEY2) 
 sub = client.get_subscription(subscription_id: 'abcd7890')
 ```
 
-### Operations
+# Operations
 
 The {Recurly::Client} contains every `operation` you can perform on the site as a list of methods. Each method is documented explaining
 the types and descriptions for each input and return type. You can view all available operations by looking at the `Instance Methods Summary` list
 on the {Recurly::Client} documentation page. Clicking a method will give you detailed information about its inputs and returns. Take the `create_account`
 operation as an example: {Recurly::Client#create_account}.
 
-### Pagination
+# Pagination
 
 Pagination is done by the class {Recurly::Pager}. All `list_*` methods on the client return an instance of this class.
 The pager has an `each` method which accepts a block for each object in the entire list. Each page is fetched automatically
 for you presenting the elements as a single enumerable.
 
@@ -115,11 +108,11 @@
 
 `limit` defaults to 20 items per page and can be set from 1 to 200. Choosing a lower limit means more network requests but smaller payloads.
 We recommend keeping the default for most cases but increasing the limit if you are planning on iterating through many pages of items (e.g. all transactions in your site).
 
 
-### Creating Resources
+# Creating Resources
 
 Currently, resources are created by passing in a `body` keyword argument in the form of a `Hash`.
 This Hash must follow the schema of the documented request type. For example, the `create_plan` operation
 takes a request of type {Recurly::Requests::PlanCreate}. Failing to conform to this schema will result in an argument
 error.
@@ -143,11 +136,11 @@
 }
 
 plan = client.create_plan(body: plan_data)
 ```
 
-### Error Handling
+# Error Handling
 
 This library currently throws 2 types of exceptions. {Recurly::Errors::APIError} and {Recurly::Errors::NetworkError}. See these 2 files for the types of exceptions you can catch:
 
 1. [API Errors](./lib/recurly/errors/api_errors.rb)
 2. [Network Errors](./lib/recurly/errors/network_errors.rb)
@@ -187,11 +180,11 @@
 rescue Recurly::Errors::NetworkError => ex
   # catch a generic network error
 end
 ```
 
-### HTTP Metadata
+# HTTP Metadata
 
 Sometimes you might want to get some additional information about the underlying HTTP request and response. Instead of
 returning this information directly and forcing the programmer to unwrap it, we inject this metadata into the top level
 resource that was returned. You can access the {Recurly::HTTP::Response} by calling `#get_response` on any {Recurly::Resource}.
 
@@ -222,10 +215,10 @@
   response = e.get_response()
   puts "Give this request id to Recurly Support: #{response.request_id}"
 end
 ```
 
-### Webhooks
+# Webhooks
 
 Recurly can send webhooks to any publicly accessible server.
 When an event in Recurly triggers a webhook (e.g., an account is opened),
 Recurly will attempt to send this notification to the endpoint(s) you specify.
 You can specify up to 10 endpoints through the application. All notifications will