diff --git a/doc/source/authentication-plugins.rst b/doc/source/authentication-plugins.rst
index 5e93c465..da742d91 100644
--- a/doc/source/authentication-plugins.rst
+++ b/doc/source/authentication-plugins.rst
@@ -38,7 +38,7 @@ They include:
   V2 identity service using an existing token.
 
 V2 identity plugins must use an `auth_url` that points to the root of a V2
-identity server URL, i.e.: `http://hostname:5000/v2.0`.
+identity server URL, i.e.: ``http://hostname:5000/v2.0``.
 
 V3 Identity Plugins
 -------------------
@@ -97,7 +97,7 @@ This will have exactly the same effect as using the single
 :py:class:`~keystoneauth1.identity.v3.PasswordMethod` above.
 
 V3 identity plugins must use an `auth_url` that points to the root of a V3
-identity server URL, i.e.: `http://hostname:5000/v3`.
+identity server URL, i.e.: ``http://hostname:5000/v3``.
 
 Federation
 ==========
@@ -136,8 +136,8 @@ Simple Plugins
 
 In addition to the Identity plugins a simple plugin that will always use the
 same provided token and endpoint is available. This is useful in situations
-where you have an ``ADMIN_TOKEN`` or in testing when you specifically know the
-endpoint you want to communicate with.
+where you have an token or in testing when you specifically know the endpoint
+you want to communicate with.
 
 It can be found at :py:class:`keystoneauth1.token_endpoint.Token`.
 
diff --git a/doc/source/using-sessions.rst b/doc/source/using-sessions.rst
index b0bf5f08..7a7b0d5f 100644
--- a/doc/source/using-sessions.rst
+++ b/doc/source/using-sessions.rst
@@ -53,7 +53,7 @@ asked for a valid token. If a valid token is available it will be used
 otherwise the authentication plugin may attempt to contact the authentication
 service and fetch a new one.
 
-An example from keystoneclient::
+An example using keystoneclient to wrap a session::
 
     >>> from keystoneauth1.identity import v3
     >>> from keystoneauth1 import session
@@ -70,8 +70,9 @@ An example from keystoneclient::
     >>> ks = client.Client(session=sess)
     >>> users = ks.users.list()
 
-As clients adopt this means of operating they will be created in a similar
-fashion by passing the Session object to the client's constructor.
+As other OpenStack client libraries adopt this means of operating they will be
+created in a similar fashion by passing the Session object to the client's
+constructor.
 
 
 Sharing Authentication Plugins
@@ -139,19 +140,19 @@ the request needs to be specified::
                                             'interface': 'public',
                                             'region_name': 'myregion'})
 
-``endpoint_filter`` accepts a number of arguments with which it can determine
-an endpoint url:
+`endpoint_filter` accepts a number of arguments with which it can determine an
+endpoint url:
 
-- ``service_type``: the type of service. For example ``identity``, ``compute``,
+- `service_type`: the type of service. For example ``identity``, ``compute``,
   ``volume`` or many other predefined identifiers.
 
-- ``interface``: the network exposure the interface has. This will be one of:
+- `interface`: the network exposure the interface has. This will be one of:
 
   - ``public``: An endpoint that is available to the wider internet or network.
   - ``internal``: An endpoint that is only accessible within the private network.
   - ``admin``: An endpoint to be used for administrative tasks.
 
-- ``region_name``: the name of the region where the endpoint resides.
+- `region_name`: the name of the region where the endpoint resides.
 
 The endpoint filter is a simple key-value filter and can be provided with any
 number of arguments. It is then up to the auth plugin to correctly use the