DOCS-10988: reword all-database roles sections

Author: steveren

source/includes/seealso-cluster-manager.rst

@@ -0,0 +1,3 @@
+See also the :authrole:`clusterManager` and
+:authrole:`clusterMonitor` roles for access to the ``config`` and
+``local`` databases.

source/reference/built-in-roles.txt

@@ -624,57 +624,61 @@ All-Database Roles
 
 .. versionchanged:: 3.4
 
-The ``admin`` database provides the following roles that apply to but
-the ``local`` and ``config`` databases in a :program:`mongod` instance
-and are roughly equivalent to their single-database equivalents:
+The following roles are available only to users on the ``admin``
+database. These roles provide privileges which apply to all
+collections except ``system.*`` collections on all databases
+except ``local`` and ``config``:
 
 .. authrole:: readAnyDatabase
 
-   Provides the same read-only permissions as :authrole:`read`, except
-   it applies to it applies to all but the ``local`` and ``config``
-   databases in the cluster. The role also provides the
-   :authaction:`listDatabases` action on the cluster as a whole.
+   Provides the same read-only privileges as :authrole:`read` on all
+   databases except ``local`` and ``config``.
+   :authrole:`readAnyDatabase` also provides the
+   :authaction:`listDatabases` privilege action on the cluster.
 
    .. versionchanged:: 3.4
 
-      Prior to 3.4, :authrole:`readAnyDatabase` includes ``local`` and
-      ``config`` databases. To provide ``read`` privileges on the
-      ``local`` database, create a user in the ``admin`` database with
-      :authrole:`read` role in the ``local`` database. See also
-      :authrole:`clusterManager` and :authrole:`clusterMonitor` role
-      for access to the ``config`` and ``local`` databases.
+      :authrole:`readAnyDatabase` no longer
+      applies to the ``local`` and ``config`` databases. To provide
+      read privileges on ``local`` and ``config``, create a
+      user on the ``admin`` database with the :authrole:`read`
+      role on the ``local`` and ``config`` databases.
+
+      .. include:: /includes/seealso-cluster-manager.rst
 
 .. authrole:: readWriteAnyDatabase
 
-   Provides the same read and write permissions as
-   :authrole:`readWrite`, except it applies to all but the ``local``
-   and ``config`` databases in the cluster. The role also provides the
-   :authaction:`listDatabases` action on the cluster as a whole.
+   Provides the same read and write privileges as
+   :authrole:`readWrite` on all databases except ``local`` and
+   ``config``. :authrole:`readWriteAnyDatabase` also provides the
+   :authaction:`listDatabases` privilege action on the cluster.
 
    .. versionchanged:: 3.4
 
-      Prior to 3.4, :authrole:`readWriteAnyDatabase` includes ``local``
-      and ``config`` databases. To provide ``readWrite`` privileges on
-      the ``local`` database, create a user in the ``admin`` database
-      with :authrole:`readWrite` role in the ``local`` database. See
-      also :authrole:`clusterManager` and :authrole:`clusterMonitor`
-      role for access to the ``config`` and ``local`` databases.
+      :authrole:`readWriteAnyDatabase` no longer
+      applies to the ``local`` and ``config`` databases. To provide
+      read and write privileges on ``local`` and ``config``,
+      create a user on the ``admin`` database with the
+      :authrole:`readWrite` role on the ``local`` and ``config``
+      databases.
+
+      .. include:: /includes/seealso-cluster-manager.rst
 
 .. authrole:: userAdminAnyDatabase
 
    Provides the same access to user administration operations as
-   :authrole:`userAdmin`, except it applies to all but the ``local``
-   and ``config`` databases in the cluster. The role also provides the
-   following actions on the cluster as a whole:
+   :authrole:`userAdmin` on all databases except ``local`` and
+   ``config``. :authrole:`userAdminAnyDatabase` also provides the
+   following privilege actions on the cluster:
 
    - :authaction:`authSchemaUpgrade`
    - :authaction:`invalidateUserCache`
    - :authaction:`listDatabases`
 
-   The role also provides the following actions on the
-   :data:`admin.system.users` and :data:`admin.system.roles` collections on
-   the ``admin`` database, and on legacy ``system.users`` collections from
-   versions of MongoDB prior to 2.6:
+   The role also provides the following privilege actions on the
+   :data:`system.users` and :data:`system.roles`
+   collections on the ``admin`` database, and on legacy
+   ``system.users`` collections from versions of MongoDB prior to 2.6:
 
    - :authaction:`collStats`
    - :authaction:`dbHash`
@@ -684,14 +688,14 @@ and are roughly equivalent to their single-database equivalents:
    - :authaction:`planCacheRead`
 
    .. versionchanged:: 2.6.4
-      :authrole:`userAdminAnyDatabase` added the following permissions
-      on the :data:`admin.system.users` and
+      :authrole:`userAdminAnyDatabase` added the following privilege
+      actions on the :data:`admin.system.users` and
       :data:`admin.system.roles` collections:
 
       - :authaction:`createIndex`
       - :authaction:`dropIndex`
 
-   The :authrole:`userAdminAnyDatabase` role does not restrict the permissions
+   The :authrole:`userAdminAnyDatabase` role does not restrict the privileges
    that a user can grant. As a result, :authrole:`userAdminAnyDatabase` users
    can grant themselves privileges in excess of their current
    privileges and even can grant themselves *all privileges*, even though the
@@ -700,24 +704,28 @@ and are roughly equivalent to their single-database equivalents:
 
    .. versionchanged:: 3.4
 
-      Prior to 3.4, :authrole:`userAdminAnyDatabase` includes ``local``
-      and ``config`` databases.
+      :authrole:`userAdminAnyDatabase` no longer
+      applies to the ``local`` and ``config`` databases.
 
+      .. include:: /includes/seealso-cluster-manager.rst
+          
 .. authrole:: dbAdminAnyDatabase
 
    Provides the same access to database administration operations as
-   :authrole:`dbAdmin`, except it applies to all but the ``local`` and
-   ``config`` databases in the cluster. The role also provides the
-   :authaction:`listDatabases` action on the cluster as a whole.
+   :authrole:`dbAdmin` on all databases except ``local`` and
+   ``config``. :authrole:`dbAdminAnyDatabase` also provides the
+   :authaction:`listDatabases` privilege action on the cluster.
 
    .. versionchanged:: 3.4
 
-      Prior to 3.4, :authrole:`dbAdminAnyDatabase` includes ``local``
-      and ``config`` databases. To provide ``dbAdmin`` privileges on
-      the ``local`` database, create a user in the ``admin`` database
-      with :authrole:`dbAdmin` role in the ``local`` database. See also
-      :authrole:`clusterManager` and :authrole:`clusterMonitor` role
-      for access to the ``config`` and ``local`` databases.
+      :authrole:`dbAdminAnyDatabase` no longer
+      applies to the ``local`` and ``config`` databases.
+      To provide ``dbAdmin`` privileges on ``local`` and ``config``,
+      create a user on the ``admin`` database with the
+      :authrole:`dbAdmin` role on the ``local`` and ``config``
+      databases.
+
+      .. include:: /includes/seealso-cluster-manager.rst
 
 .. _superuser: