fix: document having multiple operators installed (#33448)

* fix: document having multiple operators installed

closes: #32152

Signed-off-by: Steve Hawkins <shawkins@redhat.com>

* Update docs/guides/operator/installation.adoc

Co-authored-by: Václav Muzikář <vaclav@muzikari.cz>
Signed-off-by: Steven Hawkins <shawkins@redhat.com>

* Update docs/guides/operator/installation.adoc

Co-authored-by: Václav Muzikář <vaclav@muzikari.cz>
Signed-off-by: Steven Hawkins <shawkins@redhat.com>

---------

Signed-off-by: Steve Hawkins <shawkins@redhat.com>
Signed-off-by: Steven Hawkins <shawkins@redhat.com>
Co-authored-by: Václav Muzikář <vaclav@muzikari.cz>

docs/guides/operator/installation.adoc

@@ -42,6 +42,8 @@ Make sure you are installing from the *fast* channel:
 +
 image::configure-operator.png["Configure {project_name} Operator"]
 
+You may select to either have the Operator watch the namespace where it is installed, or to watch a single namespace of your choosing.
+
 <@profile.ifCommunity>
 === Installing by using kubectl without Operator Lifecycle Manager
 
@@ -62,7 +64,21 @@ kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resourc
 kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/{version}/kubernetes/kubernetes.yml
 ----
 
-Currently the Operator watches only the namespace where the Operator is installed.
+The Operator will watch the namespace where it is installed. You may optionally select a namespace with the `-n` option. 
 </@profile.ifCommunity>
 
+=== Installing Multiple Operators
+
+It is currently not fully supported for the operator to watch multiple or all namespaces. In circumstances where you want to watch multiple namespaces, you can install multiple operators.
+
+If you do this please be aware:
+
+- all Operators share the CRDs (Custom Resource Definitions) as they are installed cluster wide.
+- CRD revisions from newer Operator versions won't introduce breaking changes except for the eventual removal of fields that have been well deprecated. Thus newer CRDs are generally backward compatible.
+- the CRDs installed last will be the ones in use. This applies to OLM installations as well where the Operator version, that is installed as the last, also installs and overrides the CRDs if they exists in the cluster already.
+- older CRDs may not be forwards compatible with new fields used by newer operators. When using OLM it will check if your custom resources are compatible with the CRDs being installed, so the usage of new fields can prevent the simultaneous installation of older operator versions.
+- fields introduced by newer CRDs will not be supported by older Operators. Older Operator will fail to handle CRs that use such new fields with an error deserializing an unrecognized field.
+
+It is therefore recommended in a multiple Operator install scenario that you keep versions aligned as closely as possible to minimize the potential problems with different versions. 
+
 </@tmpl.guide>