diff --git a/README.md b/README.md
index 84735b5..df7018c 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,95 @@
+[](https://travis-ci.org/PolymerElements/iron-component-page)
+[](https://beta.webcomponents.org/element/PolymerElements/iron-component-page)
-
+### Documenting your element
-[](https://travis-ci.org/PolymerElements/iron-component-page)
+`iron-component-page` is designed to make it easy to view documentation for
+your custom element project.
-_[Demo and API docs](https://elements.polymer-project.org/elements/iron-component-page)_
+1. Install the [Polymer CLI](https://github.com/Polymer/polymer-cli) with `npm
+ install -g polymer-cli` or `yarn global add polymer-cli`. This gives you a
+ command-line interface to Polymer Analyzer (among other things).
+2. `cd` to your project directory. This can be a custom element, a full app, or
+ even a plain JavaScript library. Polymer Analyzer will discover all of the
+ interesting items recursively in your project directory.
-## <iron-component-page>
+3. Analyze your project with `polymer analyze > analysis.json`. This produces a
+ JSON descriptor file. By default `iron-component-page` will look for a file
+ called `analysis.json` (you can override this with the `descriptor-url`
+ property).
+
+4. Add `iron-component-page` as a dev dependency of your project: `bower
+ install iron-component-page --save-dev`.
+
+5. Create an HTML file to instantiate an `iron-component-page` element (e.g.
+ `index.html` or `docs.html`). Note that you may need to adjust your import
+ paths depending on your project layout:
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+6. Serve that page using any local web server, such as `polymer serve` or
+ `python -m SimpleHTTPServer`.
+
+### Routing
+
+`iron-component-page` handles URL routing (via `iron-doc-viewer`) to provide
+permanent addresses for all locations in the documentation tree, including
+scroll anchor targets.
+
+By default it uses the URL fragment for routing (e.g.
+`docs.html#/elements/my-element#property-foo`), in order to support simple
+static file hosts.
+
+To use the real URL path for routing, set the `base-href` property to the
+server mount point (e.g. `/` or `/docs/`). Note that this requires a host that
+serves the application from all paths that should be handled by the doc viewer.
+
+### Previous versions
-Loads Polymer element and behavior documentation using
-[Hydrolysis](https://github.com/PolymerLabs/hydrolysis) and renders a complete
-documentation page including demos (if available).
+The 3.x `iron-component-page` described here has major breaking changes versus
+the 1.x and 2.x versions. Previous versions were based on *Hydrolysis*, the
+predecessor to Polymer Analyzer. Major changes in the 3.x version include:
+* Uses Polymer Analyzer descriptors instead of Hydrolysis. Among other things,
+ this adds support for classes, mixins, and Polymer 2 elements.
+* Does not analyze your source in the browser. Instead, run `polymer analyze`
+ to generate an `analysis.json` file offline.
+* Replaces the element menu with a full-size navigation panel that summarizes
+ all the available documentation produced by Polymer Analyzer.
+If you still need the previous version, see the
+[2.x branch](https://github.com/PolymerElements/iron-component-page/tree/2.x).