diff --git a/doc/source/user/config/configuration.rst b/doc/source/user/config/configuration.rst
index 6f8525bde..3bbba6f96 100644
--- a/doc/source/user/config/configuration.rst
+++ b/doc/source/user/config/configuration.rst
@@ -520,7 +520,7 @@ Examples
 ``auth``
 ~~~~~~~~
 
-.. rubric:: Password-based authentication (domain-scoped)
+.. rubric:: Password-based authentication (project-scoped)
 
 .. code-block:: yaml
 
@@ -534,6 +534,18 @@ Examples
             username: admin
         region_name: RegionOne
 
+.. rubric:: Password-based authentication (domain-scoped)
+
+.. code-block:: yaml
+
+    example:
+        auth:
+            auth_url: http://example.com/identity
+            domain_id: default
+            password: password
+            username: admin
+        region_name: RegionOne
+
 .. rubric:: Password-based authentication (trust-scoped)
 
 .. code-block:: yaml
@@ -584,8 +596,8 @@ Examples
 
 .. note::
 
-    This is a toy example: by their very definition token's are short-lived.
-    You are unlikely to store them in a `clouds.yaml` file.
+    This is a toy example: by their very definition tokens are short-lived.
+    You are unlikely to store them in a ``clouds.yaml`` file.
     Instead, you would likely pass the TOTP token via the command line
     (``--os-token``) or as an environment variable (``OS_TOKEN``).
 
@@ -606,8 +618,8 @@ Examples
 
 .. note::
 
-    This is a toy example: by their very definition TOTP token's are
-    short-lived. You are unlikely to store them in a `clouds.yaml` file.
+    This is a toy example: by their very definition TOTP tokens are
+    short-lived. You are unlikely to store them in a ``clouds.yaml`` file.
     Instead, you would likely pass the TOTP token via the command line
     (``--os-passcode``) or as an environment variable (``OS_PASSCODE``).