diff --git a/doc/source/index.rst b/doc/source/index.rst
index a8e75f80..68ab879e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -2,8 +2,6 @@
  oslo.policy
 =============
 
-oslo.policy library
-
 Contents
 ========
 
@@ -22,4 +20,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index 71695137..5b495e0c 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -5,3 +5,8 @@
 At the command line::
 
     $ pip install oslo.policy
+
+Or, if you want to use it in a virtualenvwrapper::
+
+    $ mkvirtualenv oslo.policy
+    $ pip install oslo.policy
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 02672abb..521561d4 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -2,6 +2,38 @@
  Usage
 =======
 
-To use oslo.policy in a project::
+To use oslo.policy in a project, import the relevant module. For
+example::
 
-    import oslo_policy
+    from oslo_policy import policy
+
+Migrating to oslo.policy
+========================
+
+Applications using the incubated version of the policy code from Oslo aside
+from changing the way the library is imported, may need to make some extra
+changes.
+
+Changes to Enforcer Initialization
+----------------------------------
+
+The ``oslo.policy`` library no longer assumes a global configuration object is
+available. Instead the :py:class:`oslo_policy.policy.Enforcer` class has been
+changed to expect the consuming application to pass in an ``oslo.config``
+configuration object.
+
+When using policy from oslo-incubator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    enforcer = policy.Enforcer(policy_file=_POLICY_PATH)
+
+When using oslo.policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    from keystone import config
+    CONF = config.CONF
+    enforcer = policy.Enforcer(CONF, policy_file=_POLICY_PATH)