diff --git a/README.md b/README.md
index efc7ea6..a31c052 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
 # proc-macro2
 
-[Documentation](http://alexcrichton.com/proc-macro2)
+[Documentation](https://docs.rs/proc-macro2)
 
-A small shim over the `proc_macro` crate intended to multiplex the current
-stable interface (as of 2017-05-19) and the [upcoming richer
+A small shim over the `proc_macro` crate in the compiler intended to multiplex
+the current stable interface (as of 2017-07-05) and the [upcoming richer
 interface][upcoming].
 
 [upcoming]: https://github.com/rust-lang/rust/pull/40939
@@ -14,10 +14,49 @@
 * No need to go in/out through strings
 * Structured input/output
 
-My hope is that libraries ported to `proc_macro2` will be trivial to port to the
-real `proc_macro` crate once the support on nightly is stabilize.
+The hope is that libraries ported to `proc_macro2` will be trivial to port to
+the real `proc_macro` crate once the support on nightly is stabilize.
 
-This crate is still very much a work in progress
+## Usage
+
+This crate by default compiles on the stable version of the compiler. It only
+uses the stable surface area of the `proc_macro` crate upstream in the compiler
+itself. Usage is done via:
+
+```toml
+[dependencies]
+proc-macro2 = "0.1"
+```
+
+followed by
+
+```rust
+extern crate proc_macro;
+extern crate proc_macro2;
+
+#[proc_macro_derive(MyDerive)]
+pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+    let input: proc_macro2::TokenStream = input.into();
+
+    let output: proc_macro2::TokenStream = {
+        /* transform input */
+    };
+
+    output.into()
+}
+```
+
+If you'd like you can enable the `unstable` feature in this crate. This will
+cause it to compile against the **unstable and nightly-only** features of the
+`proc_macro` crate. This in turn requires a nightly compiler. This should help
+preserve span information, however, coming in from the compiler itself.
+
+You can enable this feature via:
+
+```toml
+[dependencies]
+proc-macro2 = { version = "0.1", features = ["unstable"] }
+```
 
 # License