diff --git a/doc/source/command-objects/credential.rst b/doc/source/command-objects/credential.rst
index ed8a00dbd7..538362a864 100644
--- a/doc/source/command-objects/credential.rst
+++ b/doc/source/command-objects/credential.rst
@@ -1,27 +1,113 @@
-===========
+==========
 credential
-===========
+==========
 
 Identity v3
 
 credential create
-------------------
+-----------------
 
-.. ''[consider rolling the ec2 creds into this too]''
+Create new credential
 
+.. program:: credential create
 .. code:: bash
 
     os credential create
-        --x509
-        [<private-key-file>]
-        [<certificate-file>]
+        [--type <type>]
+        [--project <project>]
+        <user> <data>
+
+.. option:: --type <type>
+
+    New credential type
+
+.. option:: --project <project>
+
+    Project which limits the scope of the credential (name or ID)
+
+.. _credential_create:
+.. describe:: <user>
+
+    User that owns the credential (name or ID)
+
+.. describe:: <data>
+
+    New credential data
+
+credential delete
+-----------------
+
+Delete credential(s)
+
+.. program:: credential delete
+.. code:: bash
+
+    os credential delete
+        <credential-id> [<credential-id> ...]
+
+.. _credential_delete:
+.. describe:: <credential-id>
+
+    ID(s) of credential to delete
+
+credential list
+---------------
+
+List credentials
+
+.. program:: credential list
+.. code:: bash
+
+    os credential list
+
+credential set
+--------------
+
+Set credential properties
+
+.. program:: credential set
+.. code:: bash
+
+    os credential set
+        [--user <user>]
+        [--type <type>]
+        [--data <data>]
+        [--project <project>]
+        <credential-id>
+
+.. option:: --user <user>
+
+    User that owns the credential (name or ID)
+
+.. option:: --type <type>
+
+    New credential type
+
+.. option:: --data <data>
+
+    New credential data
+
+.. option:: --project <project>
+
+    Project which limits the scope of the credential (name or ID)
+
+.. _credential_set:
+.. describe:: <credential-id>
+
+    ID of credential to change
 
 credential show
-----------------
+---------------
 
+Display credential details
+
+.. program:: credential show
 .. code:: bash
 
     os credential show
-        [--token]
-        [--user]
-        [--x509 [--root]]
+        <credential-id>
+
+.. _credential_show:
+.. describe:: <credential-id>
+
+    ID of credential to display
diff --git a/openstackclient/identity/v3/credential.py b/openstackclient/identity/v3/credential.py
index eeeddfa554..7e5b040f4b 100644
--- a/openstackclient/identity/v3/credential.py
+++ b/openstackclient/identity/v3/credential.py
@@ -23,14 +23,14 @@ from openstackclient.i18n import _
 
 
 class CreateCredential(command.ShowOne):
-    """Create credential command"""
+    """Create new credential"""
 
     def get_parser(self, prog_name):
         parser = super(CreateCredential, self).get_parser(prog_name)
         parser.add_argument(
             'user',
             metavar='<user>',
-            help=_('Name or ID of user that owns the credential'),
+            help=_('user that owns the credential (name or ID)'),
         )
         parser.add_argument(
             '--type',
@@ -47,8 +47,8 @@ class CreateCredential(command.ShowOne):
         parser.add_argument(
             '--project',
             metavar='<project>',
-            help=_('Project name or ID which limits the '
-                   'scope of the credential'),
+            help=_('Project which limits the scope of '
+                   'the credential (name or ID)'),
         )
         return parser
 
@@ -89,7 +89,7 @@ class DeleteCredential(command.Command):
 
 
 class ListCredential(command.Lister):
-    """List credential command"""
+    """List credentials"""
 
     def take_action(self, parsed_args):
         columns = ('ID', 'Type', 'User ID', 'Blob', 'Project ID')
@@ -103,7 +103,7 @@ class ListCredential(command.Lister):
 
 
 class SetCredential(command.Command):
-    """Set credential command"""
+    """Set credential properties"""
 
     def get_parser(self, prog_name):
         parser = super(SetCredential, self).get_parser(prog_name)
@@ -116,7 +116,7 @@ class SetCredential(command.Command):
             '--user',
             metavar='<user>',
             required=True,
-            help=_('Name or ID of user that owns the credential'),
+            help=_('User that owns the credential (name or ID)'),
         )
         parser.add_argument(
             '--type',
@@ -134,8 +134,8 @@ class SetCredential(command.Command):
         parser.add_argument(
             '--project',
             metavar='<project>',
-            help=_('Project name or ID which limits the '
-                   'scope of the credential'),
+            help=_('Project which limits the scope of '
+                   'the credential (name or ID)'),
         )
         return parser
 
@@ -159,7 +159,7 @@ class SetCredential(command.Command):
 
 
 class ShowCredential(command.ShowOne):
-    """Show credential command"""
+    """Display credential details"""
 
     def get_parser(self, prog_name):
         parser = super(ShowCredential, self).get_parser(prog_name)