diff --git a/doc/source/api.rst b/doc/source/api.rst
index af4c3b0..fffbe65 100644
--- a/doc/source/api.rst
+++ b/doc/source/api.rst
@@ -13,7 +13,7 @@ To use aodhclient in a project::
 
     >>> from aodhclient.v2 import client
     >>> aodh = client.Client(...)
-    >>> aodh.alarm.list("alarm")
+    >>> aodh.alarm.list()
 
 Reference
 ---------
@@ -21,7 +21,7 @@ Reference
 For more information, see the reference:
 
 .. toctree::
-   :maxdepth: 2 
+   :maxdepth: 2
 
    ref/v2/index
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 7fca35b..61084df 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -11,6 +11,13 @@ This is a client for Aodh API. There's :doc:`a Python API
 <shell>` (installed as :program:`aodh`). Each implements the entire
 Aodh API.
 
+.. warning::
+
+   This is a new client to interact with Aodh API. There may be differences
+   in functionality, syntax, and command line output when compared with the
+   alarm functionality provided by ceilometerclient.
+
+
 .. seealso::
 
     You may want to read the `Aodh Developer Guide`__  -- the overview, at
diff --git a/doc/source/shell.rst b/doc/source/shell.rst
index 72df845..8b4aae3 100644
--- a/doc/source/shell.rst
+++ b/doc/source/shell.rst
@@ -5,7 +5,8 @@ The :program:`aodh` shell utility
 .. highlight:: bash
 
 The :program:`aodh` shell utility interacts with Aodh API
-from the command line. It supports the entirety of the Aodh API.
+from the command line. It supports the entirety of the Aodh API excluding
+deprecated combination alarms.
 
 You'll need to provide :program:`aodh` with your OpenStack credentials.
 You can do this with the :option:`--os-username`, :option:`--os-password`,
@@ -64,14 +65,14 @@ command.
 Examples
 --------
 
-Create a resource::
+Create an alarm::
 
-    gnocchi resource create --attribute id:5a301761-f78b-46e2-8900-8b4f6fe6675a --attribute project_id:eba5c38f-c3dd-4d9c-9235-32d430471f94 -n temperature:high instance
+    aodh alarm create --name alarm1 -m cpu_util --threshold 5
 
-List resources::
+List alarms::
 
-    gnocchi resource list --type instance
+    aodh alarm list
 
-Search of resources::
+Search for alarms::
 
-    gnocchi resource search --query "project_id=5a301761-f78b-46e2-8900-8b4f6fe6675a and type=instance"
+    aodh alarm search --query "project_id=5a301761-f78b-46e2-8900-8b4f6fe6675a and type=instance"