README.md in platform-api-0.0.9 vs README.md in platform-api-0.1.0

@@ -11,19 +11,24 @@
 ```
 
 And then execute:
 
 ```
-$ bundle
+bundle
 ```
 
 Or install it yourself as:
 
 ```
-$ gem install platform-api
+gem install platform-api
 ```
 
+## API documentation
+
+Jump right to the [API documentation](http://heroku.github.io/platform-api/)
+for the nitty gritty details.
+
 ## Usage guide
 
 The best place to start using the Heroku API is the [Platform API Reference](https://devcenter.heroku.com/articles/platform-api-reference).
 It has detailed descriptions of the HTTP API, including general information
 about authentication, caching, object identifiers, rate limits, etc.  It also
@@ -255,25 +260,60 @@
 ```
 
 Hopefully this has given you a taste of how the client works.  If you have
 questions please feel free to file issues.
 
+### Building API documentation
+
+Build documentation with:
+
+```
+rake yard
+```
+
+And then visit `docs/index.html` to read it.  Alternaltely, build and publish
+it to Github Pages in one step with:
+
+```
+rake publish
+```
+
 ### Debugging
 
 Sometimes it helps to see more information about the requests flying by.  You
 can start your program or an `irb` session with the `EXCON_DEBUG=1`
 environment variable to cause request and response data to be written to
 `STDERR`.
 
-### Building API documentation
+### Passing custom headers
 
-Build documentation with:
+The various `connect` methods take an options hash that you can use to include
+custom headers to include with every request:
 
+```ruby
+client = PlatformAPI.connect('my-api-key', default_headers: {'Foo' => 'Bar'})
 ```
-rake yard
+
+### Using a custom cache
+
+By default, the `platform-api` will cache data in `~/.heroics/platform-api`.
+Use a different caching by passing in the [Moneta](https://github.com/minad/moneta)
+instance you want to use:
+
+```ruby
+client = PlatformAPI.connect('my-api-key', cache: Moneta.new(:Memory))
 ```
 
-And then visit `docs/index.html` to read it.
+### Connecting to a different host
+
+Connect to a different host by passing a host option:
+
+```ruby
+client = PlatformAPI.connect('my-api-key', host: 'api.example.com')
+```
+
+Connections are always made using HTTPS and certificates verification is
+always enabled.
 
 ## Contributing
 
 1. [Fork the repository](https://github.com/heroku/platform-api/fork).
 2. Create your feature branch: `git checkout -b my-new-feature`