diff --git a/README.md b/README.md
index 7ae7090..14591ed 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,35 @@
 # Rustdoc Types
 
-[Docs](https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types/index.html)
+[Docs](https://docs.rs/rustdoc-types/latest/rustdoc_types/)
 
-This is an export of [`rustdoc-json-types`](https://github.com/rust-lang/rust/blob/master/src/rustdoc-json-types/lib.rs)
+This crate contains the type definiions for rustdoc's currently-unstable
+`--output-format=json` flag. They can be deserialized with `serde-json` from
+the output of `cargo +nightly rustdoc -- --output-format json -Z unstable-options`:
 
-## Release Procedure
+```rust
+let json_string = std::fs::read_to_string("./target/doc/rustdoc_types.json")?;
+let krate: rustdoc_types::Crate = serde_json::from_str(&json_string)?;
+
+println!("the index has {} items", krate.index.len());
+```
+
+## Contributing
+
+This repo is a reexport of
+[`rustdoc-json-types`](https://github.com/rust-lang/rust/blob/master/src/rustdoc-json-types/lib.rs)
+from the rust repo. Any change to the contents of [`src/`](src/), should be sent
+to [`rust-lang/rust`](https://github.com/rust-lang/rust/), via their [normal
+contibution
+procudures](https://rustc-dev-guide.rust-lang.org/contributing.html). Once
+reviewed and merged there, the change will be pulled to this repo and published
+to crates.io.
+
+### Release Procedure
 
 1. Run `./update.sh` to pull code from upstream
 2. Run `cargo test`
 3. Run `./clgen.sh <old_version> <new_version>`
-4. Follow instructions to commit and push.
+4. Follow printed instructions to commit and push.
 
 ## License
 
@@ -22,7 +42,7 @@ Licensed under either of
 
 at your option.
 
-## Contribution
+### Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
diff --git a/examples/simple_usage.rs b/examples/simple_usage.rs
new file mode 100644
index 0000000..2e679fd
--- /dev/null
+++ b/examples/simple_usage.rs
@@ -0,0 +1,9 @@
+use std::error::Error;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let json_string = std::fs::read_to_string("./target/doc/rustdoc_types.json")?;
+    let krate: rustdoc_types::Crate = serde_json::from_str(&json_string)?;
+    println!("the index has {} items", krate.index.len());
+
+    Ok(())
+}