diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 43bc0d957..87269de5f 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -6,12 +6,18 @@ To use shade in a project::
 
 	import shade
 
-.. warning::
-  Several of the API methods return a ``dict`` that describe a resource.
-  It is possible to access keys of the dict as an attribute (e.g.,
-  ``server.id`` instead of ``server['id']``) to maintain some backward
-  compatibility, but attribute access is deprecated. New code should
-  assume a normal dictionary and access values via key.
+.. note::
+  API methods that return a description of an OpenStack resource (e.g.,
+  server instance, image, volume, etc.) do so using a dictionary of values
+  (e.g., ``server['id']``, ``image['name']``). This is the standard, and
+  **recommended**, way to access these resource values.
+
+  For backward compatibility, resource values can be accessed using object
+  attribute access (e.g., ``server.id``, ``image.name``). Shade uses the
+  `Munch library <https://github.com/Infinidat/munch>`_ to provide this
+  behavior. This is **NOT** the recommended way to access resource values.
+  We keep this behavior for developer convenience in the 1.x series of shade
+  releases. This will likely not be the case in future, major releases of shade.
 
 .. autoclass:: shade.OpenStackCloud
    :members: