diff --git a/doc/source/conf.py b/doc/source/conf.py
index 892b04f2a..2113f6271 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -52,6 +52,11 @@ pygments_style = 'sphinx'
 
 autodoc_member_order = "bysource"
 
+# Locations to exclude when looking for source files.
+# * Glossary is not included in any toctree, so it raised warnings, but it
+#   is explicitly linked to from the top of users/index.rst.
+exclude_patterns = ["users/glossary.rst"]
+
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
diff --git a/doc/source/contributors/index.rst b/doc/source/contributors/index.rst
new file mode 100644
index 000000000..c302d3fc3
--- /dev/null
+++ b/doc/source/contributors/index.rst
@@ -0,0 +1,2 @@
+Contributors
+============
diff --git a/doc/source/index.rst b/doc/source/index.rst
index d90a7fa1e..ad1bf301a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,54 +1,22 @@
-.. include:: ../../README.rst
+Welcome to the OpenStack SDK!
+=============================
 
-Welcome!
-========
+This documentation is split into two sections: one for `users <users/index>`_
+looking to build applications which make use of OpenStack, and another for
+those looking to `contribute <contributors/index>`_ to this project.
+
+For Users
+---------
 
 .. toctree::
    :maxdepth: 2
 
-   users/installation
-   users/usage
-   contributors/contributing
-   users/glossary
+   users/index
 
-User Guides
------------
+For Contributors
+----------------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   users/userguides/object_store
-
-High-Level Interface
---------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   users/highlevel/object_store
-
-Resource Level Classes
-----------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   users/resources/object_store/v1/container
-   users/resources/object_store/v1/obj
-
-Low-Level Classes
------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   users/connection
-   users/user_preference
-   users/session
-   users/transport
-   users/base_auth_plugin
-   users/identity_base
-   users/identity_v2
-   users/identity_v3
-   users/resource
-   users/service_filter
+   contributors/index
diff --git a/doc/source/users/index.rst b/doc/source/users/index.rst
new file mode 100644
index 000000000..23cb67a91
--- /dev/null
+++ b/doc/source/users/index.rst
@@ -0,0 +1,97 @@
+Getting started with the OpenStack SDK
+======================================
+
+For a listing of terms used throughout the SDK, including the names of
+projects and services supported by it, see the `Glossary <glossary>`_.
+
+Installation
+------------
+
+The OpenStack SDK is available on
+`PyPI <https://pypi.python.org/pypi/python-openstacksdk>`_ under the name
+**python-openstacksdk**. To install it, use ``pip``::
+
+   $ pip install python-openstacksdk
+
+User Guides
+-----------
+
+These guides walk you through how to make use of the libraries we provide
+to work with each OpenStack service. If you're looking for a cookbook
+approach, this is where you'll want to begin.
+
+.. toctree::
+   :maxdepth: 1
+
+   Connecting to an OpenStack Cloud <userguides/usage>
+   Working with data in the Object Store <userguides/object_store>
+
+API Documentation
+-----------------
+
+Service APIs are exposed through a two-layered approach. The classes
+exposed through our *Connection* interface are the place to start if you're
+an application developer consuming an OpenStack cloud. The *Resource*
+interface is the layer upon which the *Connection* is built, with
+*Connection* methods accepting and returning *Resource* objects.
+
+Connection Interface
+********************
+
+A *Connection* instance maintains your session, authentication, transport,
+and preferences, providing you with a set of higher-level interfaces to work
+with OpenStack services.
+
+.. toctree::
+   :maxdepth: 1
+
+   connection
+   user_preference
+
+Once you have a *Connection* instance, the following services may be exposed
+to you. Your user preferences determine the full set of exposed services,
+but listed below are the ones provided by this SDK by default.
+
+.. toctree::
+   :maxdepth: 1
+
+   Object Store <proxies/object_store>
+
+Resource Interface
+******************
+
+The *Resource* layer is a lower-level interface to communicate with OpenStack
+services. While the classes exposed by the *Connection* build a convenience
+layer on top of this, *Resources* can be used directly. However, the most
+common usage of this layer is in receiving an object from a class in the
+*Connection* layer, modifying it, and sending it back into the *Connection*
+layer, such as to update a resource on the server.
+
+The following services have exposed *Resource* classes.
+
+.. toctree::
+   :maxdepth: 1
+
+   Compute <resources/compute/index>
+   Database <resources/database/index>
+   Object Store <resources/object_store/index>
+
+Low-Level Classes
+*****************
+
+The following classes are not commonly used by application developers,
+but are used to construct applications to talk to OpenStack APIs. Typically
+these parts are managed through the `Connection Interface`_, but their use
+can be customized.
+
+.. toctree::
+   :maxdepth: 1
+
+   session
+   transport
+   base_auth_plugin
+   identity_base
+   identity_v2
+   identity_v3
+   resource
+   service_filter
diff --git a/doc/source/users/installation.rst b/doc/source/users/installation.rst
deleted file mode 100644
index 7c93ee202..000000000
--- a/doc/source/users/installation.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-============
-Installation
-============
-
-As a User
----------
-
-From the command line::
-
-    $ pip install python-openstacksdk
-
-Or, if you have virtualenvwrapper installed::
-
-    $ mkvirtualenv python-openstacksdk
-    $ pip install python-openstacksdk
-
-As a Developer
---------------
-
-Get the source::
-
-    $ git clone https://github.com/stackforge/python-openstacksdk
-    $ python setup.py develop
-
diff --git a/doc/source/users/highlevel/object_store.rst b/doc/source/users/proxies/object_store.rst
similarity index 100%
rename from doc/source/users/highlevel/object_store.rst
rename to doc/source/users/proxies/object_store.rst
diff --git a/doc/source/users/resources/compute/index.rst b/doc/source/users/resources/compute/index.rst
new file mode 100644
index 000000000..0bcd2c503
--- /dev/null
+++ b/doc/source/users/resources/compute/index.rst
@@ -0,0 +1,17 @@
+Compute Resources
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   v2/extension
+   v2/flavor
+   v2/image
+   v2/keypair
+   v2/limits_absolute
+   v2/limits_rate
+   v2/server
+   v2/server_interface
+   v2/server_ip
+   v2/server_meta
+   v2/server_metadata
diff --git a/doc/source/users/resources/compute/v2/extension.rst b/doc/source/users/resources/compute/v2/extension.rst
new file mode 100644
index 000000000..8d6c60891
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/extension.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.extension
+==============================
+
+.. automodule:: openstack.compute.v2.extension
+
+The Extension Class
+-------------------
+
+The ``Extension`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.extension.Extension
+   :members:
diff --git a/doc/source/users/resources/compute/v2/flavor.rst b/doc/source/users/resources/compute/v2/flavor.rst
new file mode 100644
index 000000000..a414b4fb6
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/flavor.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.flavor
+============================
+
+.. automodule:: openstack.compute.v2.flavor
+
+The Flavor Class
+----------------
+
+The ``Flavor`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.flavor.Flavor
+   :members:
diff --git a/doc/source/users/resources/compute/v2/image.rst b/doc/source/users/resources/compute/v2/image.rst
new file mode 100644
index 000000000..1b25e522e
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/image.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.image
+==========================
+
+.. automodule:: openstack.compute.v2.image
+
+The Image Class
+---------------
+
+The ``Image`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.image.Image
+   :members:
diff --git a/doc/source/users/resources/compute/v2/keypair.rst b/doc/source/users/resources/compute/v2/keypair.rst
new file mode 100644
index 000000000..cd2f36961
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/keypair.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.keypair
+============================
+
+.. automodule:: openstack.compute.v2.keypair
+
+The Keypair Class
+-----------------
+
+The ``Keypair`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.keypair.Keypair
+   :members:
diff --git a/doc/source/users/resources/compute/v2/limits_absolute.rst b/doc/source/users/resources/compute/v2/limits_absolute.rst
new file mode 100644
index 000000000..aac5598af
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/limits_absolute.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.limits_absolute
+====================================
+
+.. automodule:: openstack.compute.v2.limits_absolute
+
+The LimitsAbsolute Class
+------------------------
+
+The ``LimitsAbsolute`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.limits_absolute.LimitsAbsolute
+   :members:
diff --git a/doc/source/users/resources/compute/v2/limits_rate.rst b/doc/source/users/resources/compute/v2/limits_rate.rst
new file mode 100644
index 000000000..410f99e5e
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/limits_rate.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.limits_rate
+================================
+
+.. automodule:: openstack.compute.v2.limits_rate
+
+The LimitsRate Class
+--------------------
+
+The ``LimitsRate`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.limits_rate.LimitsRate
+   :members:
diff --git a/doc/source/users/resources/compute/v2/server.rst b/doc/source/users/resources/compute/v2/server.rst
new file mode 100644
index 000000000..6f0ddbb7d
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/server.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.server
+============================
+
+.. automodule:: openstack.compute.v2.server
+
+The Server Class
+----------------
+
+The ``Server`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.server.Server
+   :members:
diff --git a/doc/source/users/resources/compute/v2/server_interface.rst b/doc/source/users/resources/compute/v2/server_interface.rst
new file mode 100644
index 000000000..e67d9964a
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/server_interface.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.server_interface
+=====================================
+
+.. automodule:: openstack.compute.v2.server_interface
+
+The ServerInterface Class
+-------------------------
+
+The ``ServerInterface`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.server_interface.ServerInterface
+   :members:
diff --git a/doc/source/users/resources/compute/v2/server_ip.rst b/doc/source/users/resources/compute/v2/server_ip.rst
new file mode 100644
index 000000000..cdd63dad2
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/server_ip.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.server_ip
+==============================
+
+.. automodule:: openstack.compute.v2.server_ip
+
+The ServerIP Class
+------------------
+
+The ``ServerIP`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.server_ip.ServerIP
+   :members:
diff --git a/doc/source/users/resources/compute/v2/server_meta.rst b/doc/source/users/resources/compute/v2/server_meta.rst
new file mode 100644
index 000000000..cd06b5692
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/server_meta.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.server_meta
+================================
+
+.. automodule:: openstack.compute.v2.server_meta
+
+The ServerMeta Class
+--------------------
+
+The ``ServerMeta`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.server_meta.ServerMeta
+   :members:
diff --git a/doc/source/users/resources/compute/v2/server_metadata.rst b/doc/source/users/resources/compute/v2/server_metadata.rst
new file mode 100644
index 000000000..0248a1eb3
--- /dev/null
+++ b/doc/source/users/resources/compute/v2/server_metadata.rst
@@ -0,0 +1,12 @@
+openstack.compute.v2.server_metadata
+====================================
+
+.. automodule:: openstack.compute.v2.server_metadata
+
+The ServerMetadata Class
+------------------------
+
+The ``ServerMetadata`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.compute.v2.server_metadata.ServerMetadata
+   :members:
diff --git a/doc/source/users/resources/database/index.rst b/doc/source/users/resources/database/index.rst
new file mode 100644
index 000000000..962aa081d
--- /dev/null
+++ b/doc/source/users/resources/database/index.rst
@@ -0,0 +1,10 @@
+Database Resources
+======================
+
+.. toctree::
+   :maxdepth: 1
+
+   v1/database
+   v1/flavor
+   v1/instance
+   v1/user
diff --git a/doc/source/users/resources/database/v1/database.rst b/doc/source/users/resources/database/v1/database.rst
new file mode 100644
index 000000000..7148f2119
--- /dev/null
+++ b/doc/source/users/resources/database/v1/database.rst
@@ -0,0 +1,12 @@
+openstack.database.v1.database
+==============================
+
+.. automodule:: openstack.database.v1.database
+
+The Database Class
+------------------
+
+The ``Database`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.database.v1.database.Database
+   :members:
diff --git a/doc/source/users/resources/database/v1/flavor.rst b/doc/source/users/resources/database/v1/flavor.rst
new file mode 100644
index 000000000..2318d803b
--- /dev/null
+++ b/doc/source/users/resources/database/v1/flavor.rst
@@ -0,0 +1,12 @@
+openstack.database.v1.flavor
+============================
+
+.. automodule:: openstack.database.v1.flavor
+
+The Flavor Class
+----------------
+
+The ``Flavor`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.database.v1.flavor.Flavor
+   :members:
diff --git a/doc/source/users/resources/database/v1/instance.rst b/doc/source/users/resources/database/v1/instance.rst
new file mode 100644
index 000000000..e70be2fa4
--- /dev/null
+++ b/doc/source/users/resources/database/v1/instance.rst
@@ -0,0 +1,12 @@
+openstack.database.v1.instance
+==============================
+
+.. automodule:: openstack.database.v1.instance
+
+The Instance Class
+------------------
+
+The ``Instance`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.database.v1.instance.Instance
+   :members:
diff --git a/doc/source/users/resources/database/v1/user.rst b/doc/source/users/resources/database/v1/user.rst
new file mode 100644
index 000000000..817f77e89
--- /dev/null
+++ b/doc/source/users/resources/database/v1/user.rst
@@ -0,0 +1,12 @@
+openstack.database.v1.user
+==========================
+
+.. automodule:: openstack.database.v1.user
+
+The User Class
+--------------
+
+The ``User`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.database.v1.user.User
+   :members:
diff --git a/doc/source/users/resources/object_store/index.rst b/doc/source/users/resources/object_store/index.rst
new file mode 100644
index 000000000..df075e5df
--- /dev/null
+++ b/doc/source/users/resources/object_store/index.rst
@@ -0,0 +1,8 @@
+Object Store Resources
+======================
+
+.. toctree::
+   :maxdepth: 1
+
+   v1/container
+   v1/obj
diff --git a/doc/source/users/usage.rst b/doc/source/users/userguides/usage.rst
similarity index 91%
rename from doc/source/users/usage.rst
rename to doc/source/users/userguides/usage.rst
index c9c5870a9..c62b4a49b 100644
--- a/doc/source/users/usage.rst
+++ b/doc/source/users/userguides/usage.rst
@@ -1,3 +1,5 @@
+.. TODO(briancurtin): turn this into a full guide on the Connection class
+
 =====
 Usage
 =====