Updating Readme to explain options better

Author: iangreenleaf

Readme.md

@@ -21,12 +21,7 @@ Or use it on its own:
 github = require('githubot')
 ```
 
-Specify a different Github API version (default is `beta`):
-
-```coffeescripts
-module.exports = (robot) ->
-  github = require('githubot')(robot, apiVersion: 'preview')
-```
+You can pass additional [options](#options) to the constructor if needed.
 
 ## Use ##
 
@@ -90,17 +85,45 @@ This will happen with the bespoke methods as well:
 gh.branches "githubot", (branches) ->
 ```
 
-### Options ###
+## Options ##
+
+### Passing options ###
+
+Options may be passed to githubot in three different ways,
+in increasing order of precedence:
+
+1. Through shell environment variables.
+2. Through the constructor:
+
+   ```coffeescript
+   github = require('githubot')(robot, apiVersion: 'preview')
+   ```
+3. Using `withOptions`, which lets you pass options to only some requests:
+
+   ```coffeescript
+   github = require('githubot')(robot)
+   preview = github.withOptions(apiVersion: 'preview')
+   # Uses preview API
+   preview.get '/preview/feature', -> # ...
+   # Uses regular API
+   github.get '/regular/feature', -> # ...
+   ```
+
+### Available options ###
 
-* `HUBOT_GITHUB_TOKEN`: GitHub API token. Required to perform authenticated actions.
+* `token`/`process.env.HUBOT_GITHUB_TOKEN`:
+  GitHub API token. Required to perform authenticated actions.
 
-* `HUBOT_GITHUB_USER`: Default GitHub username to use if one is not given.
+* `defaultUser`/`process.env.HUBOT_GITHUB_USER`:
+  Default GitHub username to use if one is not given.
 
-* `HUBOT_GITHUB_API`: The base API URL. This is useful for Enterprise Github installations.
+* `apiRoot`/`process.env.HUBOT_GITHUB_API`:
+  The base API URL. This is useful for Enterprise Github installations.
 
-  For example, `HUBOT_GITHUB_API='http://myprivate.github.int'`
+  For example, `HUBOT_GITHUB_API='https://myprivate.github.int'`
 
-* `HUBOT_CONCURRENT_REQUESTS`: Limits the allowed number of concurrent requests to the GitHub API. Defaults to 20.
+* `concurrentRequests`/`process.env.HUBOT_CONCURRENT_REQUESTS`:
+  Limits the allowed number of concurrent requests to the GitHub API. Defaults to 20.
 
 ## Bespoke API access ##