diff --git a/docs/reference/operator_parameters.md b/docs/reference/operator_parameters.md
index 264c0b559..20771078f 100644
--- a/docs/reference/operator_parameters.md
+++ b/docs/reference/operator_parameters.md
@@ -253,14 +253,13 @@ configuration they are grouped under the `kubernetes` key.
 
 * **infrastructure_roles_secret_name**
   *deprecated*: namespaced name of the secret containing infrastructure roles
-  names and passwords.
+  with user names, passwords and role membership.
 
 * **infrastructure_roles_secrets**
   array of infrastructure role definitions which reference existing secrets
-  and specify the keys for extract credentials from them such as user name,
-  password and role membership. For the configmap this has to be a string
-  which allows referencing only one infrastructure roles secret.
-  The default is empty.
+  and specify the key names from which user name, password and role membership
+  are extracted. For the ConfigMap this has to be a string which allows
+  referencing only one infrastructure roles secret. The default is empty.
 
 * **pod_role_label**
   name of the label assigned to the Postgres pods (and services/endpoints) by
diff --git a/docs/user.md b/docs/user.md
index 29e9594c3..a4b1424b8 100644
--- a/docs/user.md
+++ b/docs/user.md
@@ -154,7 +154,7 @@ Infrastructure roles can be specified by the `infrastructure_roles_secrets`
 parameter where you can reference multiple existing secrets. Prior to `v1.6.0`
 the operator could only reference one secret with the
 `infrastructure_roles_secret_name` option. However, this secret could contain
-multiple roles using the same set of keys with incremented indexes.
+multiple roles using the same set of keys plus incrementing index.
 
 ```yaml
 apiVersion: v1
@@ -172,10 +172,10 @@ The block above describes the infrastructure role 'dbuser' with password
 'secret' that is a member of the 'operator' role. The resulting role will
 automatically be a login role.
 
-With the new option the user can configure the names of secret keys that
-contain the user name, password etc. The secret itself is referenced by the
+With the new option users can configure the names of secret keys that contain
+the user name, password etc. The secret itself is referenced by the
 `secretname` key. If the secret uses a template for multiple roles as described
-above, list them as separately.
+above list them separately.
 
 ```yaml
 apiVersion: v1