diff --git a/doc/source/index.rst b/doc/source/index.rst
index be6dad0..2f5775c 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -8,5 +8,6 @@ Contents:
 
    readme
    installation
-   usage
+   usage_cli
+   usage_api
    contributing
diff --git a/doc/python_api.rst b/doc/source/usage_api.rst
similarity index 80%
rename from doc/python_api.rst
rename to doc/source/usage_api.rst
index 032e46b..ecc0127 100644
--- a/doc/python_api.rst
+++ b/doc/source/usage_api.rst
@@ -10,9 +10,9 @@ Usage
 First, create an Almanach Client instance with your credentials::
 
     >>> from almanachclient.v1.client import Client
-    >>> almanach = Client(URL, AUTH_TOKEN)
+    >>> almanach = Client(ALMANACH_URL, AUTH_TOKEN)
 
-Here ``URL`` will be a string that represents the url of your API.
+Here ``ALMANACH_URL`` will be a string that represents the url of Almanach API.
 ``AUTH_TOKEN`` will be the authorization token you use to acces the API.
 
 
@@ -20,7 +20,7 @@ You can also create a Keystone Client instance and access the API with it::
 
     >>> from almanachclient.keystone_client import KeystoneClient
     >>> keystone_client = KeystoneClient(KEYSTONE_URL, USERNAME, PASSWORD, SERVICE, REGION)
-    >>> keystone_client.get_endpoint_url('admin')
+    >>> almanach_url = keystone_client.get_endpoint_url('admin')
 
 In this case ``KEYSTONE_URL`` will be a string that represents the url of your keystone catalog.
 The nature of ``USERNAME`` and ``PASSWORD`` speak for themselves. ``SERVICE`` will be a string
@@ -30,13 +30,14 @@ you use to identify the "almanach" service. ``REGION`` is used to determine whic
 
 Examples
 --------
+
 >>> import datetime
 >>> from almanachclient.v1.client import Client
 
->>> start_date = datetime.datetime(2017,01,05)
->>> end_date = datetime.datetime(2017,02,05)
+>>> start_date = datetime.datetime(2017, 01, 05)
+>>> end_date = datetime.datetime(2017, 02, 05)
 
->>> almanach = Client('http://api.region.example.org',  'myApiAuthorizationToken')
+>>> almanach = Client('http://api.region.example.org', 'myApiAuthorizationToken')
 >>> almanach.get_info()
 
 >>> almanach.get_volume_types()
diff --git a/doc/source/usage.rst b/doc/source/usage_cli.rst
similarity index 100%
rename from doc/source/usage.rst
rename to doc/source/usage_cli.rst