(DOCS-13939): minor improvements per feedback (#411)

* (DOCS-13939): minor improvements per feedback

* (DOCS-13939): fix build warnings

Author: jwilliams-mongo

conf.py

@@ -130,6 +130,8 @@
     '.. |json| replace:: :abbr:`JSON (Javascript Object Notation)`',
     '.. |jedec| replace:: :abbr:`JEDEC (Joint Electron Device Engineering Council Solid State Technology Association)`',
     '.. |jvm| replace:: :abbr:`JVM (Java Virtual Machine)`',
+    '.. |k8s-cr| replace:: `ClusterRole <https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole>`__',
+    '.. |k8s-crb| replace:: `ClusterRoleBinding <https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding>`__',
     '.. |k8s-configmaps| replace:: `ConfigMaps <https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/>`__',
     '.. |k8s-configmap| replace:: `ConfigMap <https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/>`__',
     '.. |k8s-custom-resource| replace:: `Custom Resource <https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/>`__',
@@ -159,6 +161,7 @@
     '.. |k8s-secret| replace:: `secret <https://kubernetes.io/docs/concepts/configuration/secret/>`__',
     '.. |k8s-statefulsets| replace:: `StatefulSets <https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/>`__',
     '.. |k8s-statefulset| replace:: `StatefulSet <https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/>`__',
+    '.. |k8s-webhook| replace:: `Webhook <https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#what-are-admission-webhooks>`__',
     '.. |k8s| replace:: Kubernetes',
     '.. |kdc| replace:: :abbr:`KDC (Key Distribution Center)`',
     '.. |kmip| replace:: :abbr:`KMIP (Key Management Interoperability)`',

source/includes/op-setting-descs/watch-namespace.rst

@@ -5,10 +5,9 @@ the Operator's ServiceAccount :k8sdocs:`can access
 this namespace.
 
 Use **\*** to specify *all namespaces*. To watch all namespaces, you
-must also assign the `ClusterRole
-<https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole>`__
-to the ``mongodb-enterprise-operator`` ServiceAccount,
-which is the ServiceAccount used to run the |k8s-op-short|.
+must also assign the |k8s-cr| to the ``mongodb-enterprise-operator``
+ServiceAccount, which is the ServiceAccount used to run the
+|k8s-op-short|.
 
 .. include:: /includes/admonitions/fact-create-service-account-namespaces.rst
 

source/tutorial/plan-k8s-op-considerations.txt

@@ -60,11 +60,11 @@ them every three weeks.
 Validation Webhook
 ------------------
 
-The |k8s-op-short| uses a webhook to prevent users from applying
+The |k8s-op-short| uses a |k8s-webhook| to prevent users from applying
 invalid resource definitions. The webhook rejects invalid requests.
 The |k8s-op-short| doesn't create or update the resource.
 
-The ``ClusterRole`` and ``ClusterRoleBinding`` for the webhook are
+The |k8s-cr| and |k8s-crb| for the webhook are
 included in the default configuration files that you apply during
 installation. To create the role and binding, you must have
 :k8sdocs:`cluster-admin privileges </reference/access-authn-authz/rbac/#user-facing-roles>`.
@@ -98,7 +98,7 @@ errors, the |k8s-op-short| issues warnings.
 --------------------------------
 
 You can deploy the |k8s-op-short| with different scopes based on where
-you want to deploy |onprem| and |k8s-mdbrscs| resources:
+you want to deploy |onprem| and |k8s-mdbrscs|:
 
 - :ref:`ns-scope-same-ns` *(Default)*
 - :ref:`ns-scope-different-ns`