diff --git a/README.md b/README.md
index 76c84f7..d66460e 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,21 @@
-workers + graphql playground
+# workers-graphql-server
 
-deploying this project requires a KV binding called `GRAPHQL_ON_WORKERS` to be defined for your application. if you don't want to set this up, comment out [this line](https://github.com/signalnerve/workers-graphql/blob/master/src/handlers/apollo.js#L43) before deploy
+An [Apollo GraphQL](https://www.apollographql.com/) server, built with [Cloudflare Workers](https://workers.cloudflare.com). Includes a GraphiQL route for testing requests.
+
+[Try a demo by looking at the GraphiQL explorer](https://graphql-on-workers.signalnerve.com/graphiql).
+
+## Usage
+
+You can begin building your own Workers GraphQL server by [installing Wrangler](https://workers.cloudflare.com/docs/quickstart/), the Workers command-line tool, and generating a new project:
+
+```
+wrangler generate my-graphql-server https://github.com/signalnerve/workers-graphql-server
+```
+
+The source for this project includes an external REST data source, and defined types for the [PokeAPI](https://pokeapi.co/), as an example of how to integrate external APIs.
+
+By the way - as a fullstack developer who _loves GraphQL_, and the developer advocate for Cloudflare Workers, I would love to see what you build with this! Let me know [on Twitter](https://twitter.com/signalnerve)!
+
+## License
+
+This project is licensed with the [MIT License](https://github.com/signalnerve/workers-graphql-server/blob/master/LICENSE).