diff --git a/README.md b/README.md
index a7828852..33e4f988 100644
--- a/README.md
+++ b/README.md
@@ -6,46 +6,15 @@
 [![Travis](https://img.shields.io/travis/michael/github.svg?maxAge=60)][travis-ci]
 <!-- [![Codecov](https://img.shields.io/codecov/c/github/michael/github.svg?maxAge=2592000)][codecov] -->
 
-Github.js provides a minimal higher-level wrapper around Github's API. It was concieved in the context of
-[Prose][prose], a content editor for GitHub.
+Github.js provides a minimal higher-level wrapper around Github's API.
 
-## [Read the docs][docs]
-
-## Installation
-Github.js is available from `npm` or [unpkg][unpkg].
-
-```shell
-npm install github-api
-```
-
-```html
-<!-- just github-api source (5.3kb) -->
-<script src="https://unpkg.com/github-api/dist/GitHub.min.js"></script>
-
-<!-- standalone (20.3kb) -->
-<script src="https://unpkg.com/github-api/dist/GitHub.bundle.min.js"></script>
-```
-
-## Compatibility
-Github.js is tested on Node:
-* 6.x
-* 5.x
-* 4.x
-* 0.12
-
-## GitHub Tools
-
-The team behind Github.js has created a whole organization, called [GitHub Tools](https://github.com/github-tools),
-dedicated to GitHub and its API. In the near future this repository could be moved under the GitHub Tools organization
-as well. In the meantime, we recommend you to take a look at other projects of the organization.
-
-## Samples
+## Usage
 
 ```javascript
 /*
    Data can be retrieved from the API either using callbacks (as in versions < 1.0)
-   or using a new promise-based API. For now the promise-based API just returns the
-   raw HTTP request promise; this might change in the next version.
+   or using a new promise-based API. The promise-based API returns the raw Axios
+   request promise.
  */
 import GitHub from 'github-api';
 
@@ -62,52 +31,70 @@ gist.create({
    }
 }).then(function({data}) {
    // Promises!
-   let gistJson = data;
-   gist.read(function(err, gist, xhr) {
-      // if no error occurred then err == null
-
-      // gistJson === httpResponse.data
-
-      // xhr === httpResponse
-   });
+   let createdGist = data;
+   return gist.read();
+}).then(function({data}) {
+   let retrievedGist = data;
+   // do interesting things
 });
 ```
 
 ```javascript
-import GitHub from 'github-api';
+var GitHub = require('github-api');
 
 // basic auth
-const gh = new GitHub({
+var gh = new GitHub({
    username: 'FOO',
    password: 'NotFoo'
+   /* also acceptable:
+      token: 'MY_OAUTH_TOKEN'
+    */
 });
 
-const me = gh.getUser();
+var me = gh.getUser(); // no user specified defaults to the user for whom credentials were provided
 me.listNotifications(function(err, notifications) {
    // do some stuff
 });
 
-const clayreimann = gh.getUser('clayreimann');
-clayreimann.listStarredRepos()
-   .then(function({data: reposJson}) {
-      // do stuff with reposJson
-   });
+var clayreimann = gh.getUser('clayreimann');
+clayreimann.listStarredRepos(function(err, repos) {
+   // look at all the starred repos!
+});
 ```
 
-```javascript
-var GitHub = require('github-api');
+## API Documentation
 
-// token auth
-var gh = new GitHub({
-   token: 'MY_OAUTH_TOKEN'
-});
+[API documentation][docs] is hosted on github pages, and is generated from JSDoc; any contributions
+should include updated JSDoc.
 
-var yahoo = gh.getOrganization('yahoo');
-yahoo.listRepos(function(err, repos) {
-   // look at all the repos!
-})
+## Installation
+Github.js is available from `npm` or [unpkg][unpkg].
+
+```shell
+npm install github-api
 ```
 
+```html
+<!-- just github-api source (5.3kb) -->
+<script src="https://unpkg.com/github-api/dist/GitHub.min.js"></script>
+
+<!-- standalone (20.3kb) -->
+<script src="https://unpkg.com/github-api/dist/GitHub.bundle.min.js"></script>
+```
+
+## Compatibility
+Github.js is tested on Node:
+* 6.x
+* 5.x
+* 4.x
+* 0.12
+
+## GitHub Tools
+
+The team behind Github.js has created a whole organization, called [GitHub Tools](https://github.com/github-tools),
+dedicated to GitHub and its API. In the near future this repository could be moved under the GitHub Tools organization
+as well. In the meantime, we recommend you to take a look at other projects of the organization.
+
 [codecov]: https://codecov.io/github/michael/github?branch=master
 [docs]: http://michael.github.io/github/
 [gitter]: https://gitter.im/michael/github