Updated README based on the notes from our chat

Still needs (from you guys):
- main dependency to the credentials directory and credential files, or do a small unit test to show how to use it
- under "Usage," an example with two different tokens with two different scopes
- a test case with the “test credentials” in JSON files that uses the normal setup, and mock the OAuth provider with some mock REST service
- an example showing how we use it
- more documentation of the config options

README.md

@@ -1,14 +1,34 @@
-# tokens library
+## Tokens
 
-A Java library that keeps OAuth 2.0 service access tokens in memory for your usage.
+**Tokens** is a Java library for verifying and storing OAuth 2.0 service access tokens. It is resilient, configurable, and production-tested, and works with all JVM languages.
 
 [![Build Status](https://travis-ci.org/zalando-stups/tokens.svg?branch=master)](https://travis-ci.org/zalando-stups/tokens)
 [![Javadoc](https://javadoc-emblem.rhcloud.com/doc/org.zalando.stups/tokens/badge.svg)](http://www.javadoc.io/doc/org.zalando.stups/tokens)
 ![Maven Central](https://img.shields.io/maven-central/v/org.zalando.stups/tokens.svg)
 [![Coverage Status](https://coveralls.io/repos/zalando-stups/tokens/badge.svg?branch=master)](https://coveralls.io/r/zalando-stups/tokens?branch=master)
 [![codecov.io](https://codecov.io/github/zalando-stups/tokens/coverage.svg?branch=master)](https://codecov.io/github/zalando-stups/tokens?branch=master)
 
-## Maven dependency
+### Project Features and Functionality
+
+Some of the features Tokens offers:
+
+- support for credential rotation, by reading them on-demand from the file system
+- extensiblity with a credentials provider
+- configuration flexibility; specify multiple tokens with different scopes
+- the ability to inject fixed OAuth2 access tokens
+
+Tokens can be useful to devs (at any company, large or small) who are working with highly-distributed microservices deployed in the cloud and need to authenticate the traffic generated when accessing APIs. For example, if your team wants to consume an API with OAuth2 credentials, Tokens will fetch the tokens for you. Then you just [add scopes](#Usage) in the token. 
+
+When creating tokens, it's easy to make a lot of mistakes. Tokens aims to save you hassle and time.
+
+### Prerequisites
+
+- Maven
+- [Apache-HttpClient](https://mvnrepository.com/artifact/org.apache.httpcomponents/httpclient)
+
+#### Maven Dependency
+
+Add it with:
 
 ```xml
 <dependency>
@@ -18,9 +38,9 @@ A Java library that keeps OAuth 2.0 service access tokens in memory for your usa
 </dependency>
 ```
 
-### Apache-Httpclient is also needed.
+####Apache-HttpClient
 
-So, you also have to add it with:
+Add it with:
 
 ```xml
 <dependency>
@@ -30,7 +50,7 @@ So, you also have to add it with:
 </dependency>
 ```
 
-## Usage
+### Usage
 
 ```java
 AccessTokens tokens = Tokens.createAccessTokensWithUri(new URI("https://example.com/access_tokens"))
@@ -54,18 +74,21 @@ while (true) {
 }
 ```
 
-## Local testing
+### Local Testing
 
-The "tokens" library allows injecting fixed OAuth2 access tokens via the `OAUTH2_ACCESS_TOKENS` environment variable.
-This allows testing applications using the library locally with personal OAuth2 tokens (e.g. generated by "zign"):
+With Tokens, you can inject fixed OAuth2 access tokens via the `OAUTH2_ACCESS_TOKENS` environment variable and test applications locally with personal OAuth2 tokens:
 
 ```bash
 $ MY_TOKEN=$(zign token -n mytok)
 $ export OAUTH2_ACCESS_TOKENS=mytok=$MY_TOKEN
 $ lein repl # start my local Clojure app using the tokens library
 ```
 
-## License
+### Contributing
+
+This project welcomes contributions, including bug fixes and documentation enhancements. To contribute, please use the Issues Tracker to let us know what you would like to do. We'll respond, and go from there.
+
+### License
 
 Copyright © 2015 Zalando SE