SRVCOM-1288 + SRVCOM-1664: clean up install docs, add prereqs and context attributes

abrennan89 · abrennan89 · commit 2d62f113d4d1 · 2022-02-04T13:50:29.000-06:00
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -3193,8 +3193,6 @@ Topics:
 #- Name: Get started
 #  File: serverless-getting-started
 # uncomment once new content is added for this
-- Name: Update
-  File: serverless-update
 - Name: Develop
   Dir: develop
   Topics:
diff --git a/modules/knative-serving-advanced-config.adoc b/modules/knative-serving-advanced-config.adoc
@@ -2,8 +2,9 @@
 //
 // * /serverless/install/installing-knative-serving.adoc
 
+:_content-type: REFERENCE
 [id="knative-serving-advanced-config_{context}"]
-= Knative Serving advanced configuration options
+= Advanced configuration options
 
 This section provides information about advanced configuration options for Knative Serving.
 
diff --git a/modules/serverless-cluster-sizing-req.adoc b/modules/serverless-cluster-sizing-req.adoc
@@ -1,5 +1,10 @@
+// Module included in the following assemblies:
+//
+// * /serverless/install/install-serverless-operator.adoc
+
+:_content-type: REFERENCE
 [id="serverless-cluster-sizing-req_{context}"]
-= Defining cluster size requirements for an {ServerlessProductName} installation
+= Defining cluster size requirements
 
 To install and use {ServerlessProductName}, the {product-title} cluster must be sized correctly.
 
@@ -9,3 +14,5 @@ The following requirements relate only to the pool of worker machines of the {pr
 ====
 
 The total size requirements to run {ServerlessProductName} are dependent on the applications deployed. By default, each pod requests approximately 400m of CPU, so the minimum requirements are based on this value. Lowering the actual CPU request of applications can increase the number of possible replicas.
+
+If you have high availability (HA) enabled on your cluster, this requires between 0.5 - 1.5 cores and between 200MB - 2GB of memory for each replica of the Knative Serving control plane.
diff --git a/modules/serverless-deleting-crds.adoc b/modules/serverless-deleting-crds.adoc
@@ -1,21 +1,22 @@
 // Module included in the following assemblies:
 //
-//  * serverless/admin_guide/removing-openshift-serverless.adoc
+//  * serverless/install/removing-openshift-serverless.adoc
 
+:_content-type: PROCEDURE
 [id="serverless-deleting-crds_{context}"]
 = Deleting {ServerlessProductName} custom resource definitions
 
-After uninstalling the {ServerlessProductName}, the Operator and API custom resource definitions (CRDs) remain on the cluster.
-You can use the following procedure to remove the remaining CRDs.
+After uninstalling the {ServerlessProductName}, the Operator and API custom resource definitions (CRDs) remain on the cluster. You can use the following procedure to remove the remaining CRDs.
 
 [IMPORTANT]
 ====
-Removing the Operator and API CRDs also removes all resources that were defined using them, including Knative services.
+Removing the Operator and API CRDs also removes all resources that were defined by using them, including Knative services.
 ====
 
 .Prerequisites
 
-* You uninstalled Knative Serving and removed the {ServerlessOperatorName}.
+* You have access to an {product-title} account with cluster administrator access.
+* You have uninstalled Knative Serving and removed the {ServerlessOperatorName}.
 
 .Procedure
 
diff --git a/modules/serverless-install-eventing-web-console.adoc b/modules/serverless-install-eventing-web-console.adoc
@@ -2,8 +2,17 @@
 //
 //  * /serverless/install/installing-knative-eventing.adoc
 
+:_content-type: PROCEDURE
 [id="serverless-install-eventing-web-console_{context}"]
-= Installing Knative Eventing using the web console
+= Installing Knative Eventing by using the web console
+
+You can use the following procedure to install Knative Eventing by using the {product-title} web console.
+
+.Prerequisites
+
+* You have access to an {product-title} account with cluster administrator access.
+* You have logged into the {product-title} web console.
+* You have installed the {ServerlessOperatorName}.
 
 .Procedure
 
diff --git a/modules/serverless-install-eventing-yaml.adoc b/modules/serverless-install-eventing-yaml.adoc
@@ -1,9 +1,17 @@
 // Module included in the following assemblies:
 //
-//  * serverless/installing_serverless/installing-knative-eventing.adoc
+// * /serverless/install/installing-knative-eventing.adoc
 
+:_content-type: PROCEDURE
 [id="serverless-install-eventing-yaml_{context}"]
-= Installing Knative Eventing using YAML
+= Installing Knative Eventing by using YAML
+
+You can use the following procedure to install Knative Eventing by applying YAML files.
+
+.Prerequisites
+
+* You have access to an {product-title} account with cluster administrator access.
+* You have installed the {ServerlessOperatorName}.
 
 .Procedure
 
diff --git a/modules/serverless-install-serving-web-console.adoc b/modules/serverless-install-serving-web-console.adoc
@@ -2,8 +2,17 @@
 //
 //  * serverless/install/installing-knative-serving.adoc
 
+:_content-type: PROCEDURE
 [id="serverless-install-serving-web-console_{context}"]
-= Installing Knative Serving using the web console
+= Installing Knative Serving by using the web console
+
+You can use the following procedure to install Knative Serving by using the {product-title} web console.
+
+.Prerequisites
+
+* You have access to an {product-title} account with cluster administrator access.
+* You have logged into the {product-title} web console.
+* You have installed the {ServerlessOperatorName}.
 
 .Procedure
 
diff --git a/modules/serverless-install-serving-yaml.adoc b/modules/serverless-install-serving-yaml.adoc
@@ -1,9 +1,17 @@
 // Module included in the following assemblies:
 //
-//  * serverless/installing_serverless/installing-knative-serving.adoc
+// * /serverless/install/installing-knative-serving.adoc
 
+:_content-type: PROCEDURE
 [id="serverless-install-serving-yaml_{context}"]
-= Installing Knative Serving using YAML
+= Installing Knative Serving by using YAML
+
+You can use the following procedure to install Knative Serving by applying YAML files.
+
+.Prerequisites
+
+* You have access to an {product-title} account with cluster administrator access.
+* You have installed the {ServerlessOperatorName}.
 
 .Procedure
 
diff --git a/modules/serverless-install-web-console.adoc b/modules/serverless-install-web-console.adoc
@@ -2,15 +2,16 @@
 //
 // * /serverless/install/install-serverless-operator.adoc
 
+:_content-type: PROCEDURE
 [id="serverless-install-web-console_{context}"]
 = Installing the {ServerlessOperatorName}
 
-This procedure describes how to install and subscribe to the {ServerlessOperatorName} from the OperatorHub using the {product-title} web console.
+This procedure describes how to install and subscribe to the {ServerlessOperatorName} from the OperatorHub by using the {product-title} web console.
 
-[IMPORTANT]
-====
-Before upgrading to the latest Serverless release, you must remove the community Knative Eventing Operator if you have previously installed it. Having the Knative Eventing Operator installed prevents you from being able to install the latest version of Knative Eventing using the {ServerlessOperatorName}.
-====
+.Prerequisites
+
+* You have access to an {product-title} account with cluster administrator access.
+* You have logged into the {product-title} web console.
 
 .Procedure
 
@@ -21,15 +22,21 @@ Before upgrading to the latest Serverless release, you must remove the community
 . Review the information about the Operator and click *Install*.
 
 . On the *Install Operator* page:
+
 .. The *Installation Mode* is *All namespaces on the cluster (default)*. This mode installs the Operator in the default `openshift-serverless` namespace to watch and be made available to all namespaces in the cluster.
+
 .. The *Installed Namespace* will be `openshift-serverless`.
+
 .. Select the *stable* channel as the *Update Channel*. The *stable* channel will enable installation of the latest stable release of the {ServerlessOperatorName}.
+
 .. Select *Automatic* or *Manual* approval strategy.
 
 . Click *Install* to make the Operator available to the selected namespaces on this {product-title} cluster.
 
 . From the *Catalog* -> *Operator Management* page, you can monitor the {ServerlessOperatorName} subscription's installation and upgrade progress.
+
 .. If you selected a *Manual* approval strategy, the subscription's upgrade status will remain *Upgrading* until you review and approve its install plan. After approving on the *Install Plan* page, the subscription upgrade status moves to *Up to date*.
+
 .. If you selected an *Automatic* approval strategy, the upgrade status should resolve to *Up to date* without intervention.
 
 .Verification
diff --git a/modules/serverless-uninstalling-knative-eventing.adoc b/modules/serverless-uninstalling-knative-eventing.adoc
@@ -1,15 +1,20 @@
 // Module included in the following assemblies:
 //
-// * serverless/admin_guide/removing-openshift-serverless.adoc
+// * serverless/install/removing-openshift-serverless.adoc
 
+:_content-type: PROCEDURE
 [id="serverless-uninstalling-knative-eventing_{context}"]
 = Uninstalling Knative Eventing
 
-To uninstall Knative Eventing, you must remove its custom resource and delete the `knative-eventing` namespace.
+To uninstall Knative Eventing, you must remove its custom resource (CR) and delete the `knative-eventing` namespace.
+
+.Prerequisites
+
+* You have access to an {product-title} account with cluster administrator access.
 
 .Procedure
 
-. Delete the `knative-eventing` custom resource:
+. Delete the `knative-eventing` CR:
 +
 [source,terminal]
 ----
diff --git a/modules/serverless-uninstalling-knative-serving.adoc b/modules/serverless-uninstalling-knative-serving.adoc
@@ -1,15 +1,20 @@
 // Module included in the following assemblies:
 //
-// * serverless/admin_guide/removing-openshift-serverless.adoc
+// * serverless/install/removing-openshift-serverless.adoc
 
+:_content-type: PROCEDURE
 [id="serverless-uninstalling-knative-serving_{context}"]
 = Uninstalling Knative Serving
 
-To uninstall Knative Serving, you must remove its custom resource and delete the `knative-serving` namespace.
+To uninstall Knative Serving, you must remove its custom resource (CR) and delete the `knative-serving` namespace.
+
+.Prerequisites
+
+* You have access to an {product-title} account with cluster administrator access.
 
 .Procedure
 
-. Delete the `knative-serving` custom resource:
+. Delete the `knative-serving` CR:
 +
 [source,terminal]
 ----
diff --git a/modules/serverless-upgrade-sub-channel.adoc b/modules/serverless-upgrade-sub-channel.adoc
diff --git a/serverless/install/install-serverless-operator.adoc b/serverless/install/install-serverless-operator.adoc
@@ -7,35 +7,39 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-This guide walks cluster administrators through installing the {ServerlessOperatorName} to an {product-title} cluster.
+You can install the {ServerlessOperatorName} to an {product-title} cluster by following the procedures in this document.
 
-[NOTE]
-====
-{ServerlessProductName} is supported for installation in a restricted network environment. For more information, see xref:../../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks].
-====
+[id="install-serverless-operator-before-you-begin"]
+== Before you begin
+
+Read the following information about supported configurations and prerequisites before you install {ServerlessProductName}.
+
+* {ServerlessProductName} is supported for installation in a restricted network environment.
 
-[NOTE]
+* {ServerlessProductName} currently cannot be used in a multi-tenant configuration on a single cluster.
+
+[IMPORTANT]
 ====
-{ServerlessProductName} currently cannot be used in a multi-tenant configuration on a single cluster.
+Before upgrading to the latest Serverless release, you must remove the community Knative Eventing Operator if you have previously installed it. Having the Knative Eventing Operator installed prevents you from being able to install the latest version of Knative Eventing using the {ServerlessOperatorName}.
 ====
 
-include::modules/serverless-cluster-sizing-req.adoc[leveloffset=+1]
+include::modules/serverless-cluster-sizing-req.adoc[leveloffset=+2]
+
+[id="install-serverless-operator-scaling-with-machinesets"]
+=== Scaling your cluster using machine sets
 
-If you have high availability (HA) enabled on your cluster, this requires between 0.5 - 1.5 cores and between 200MB - 2GB of memory for each replica of the Knative Serving control plane.
+You can use the {product-title} `MachineSet` API to manually scale your cluster up to the desired size. The minimum requirements usually mean that you must scale up one of the default machine sets by two additional machines. See xref:../../machine_management/manually-scaling-machineset.adoc#manually-scaling-machineset[Manually scaling a machine set].
 
-HA is enabled for some Knative Serving components by default. You can disable HA by following the documentation on xref:../../serverless/admin_guide/serverless-ha.adoc#serverless-ha[Configuring high availability replicas on {ServerlessProductName}].
+include::modules/serverless-install-web-console.adoc[leveloffset=+1]
 
-[id="installing-openshift-serverless-scaling-with-machinesets"]
-== Scaling your cluster using machine sets
+[id="additional-resources_install-serverless-operator"]
+== Additional resources
 
-You can use the {product-title} `MachineSet` API to manually scale your cluster up to the desired size.
-The minimum requirements usually mean that you must scale up one of the default machine sets by two additional machines.
-See xref:../../machine_management/manually-scaling-machineset.adoc#manually-scaling-machineset[Manually scaling a machine set].
+* For more information about using {ServerlessProductName} on a restricted network environment, see xref:../../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks].
 
-include::modules/serverless-install-web-console.adoc[leveloffset=+1]
+* HA is enabled for some Knative components by default. You can configure HA by following the documentation on xref:../../serverless/admin_guide/serverless-ha.adoc#serverless-ha[Configuring high availability replicas on {ServerlessProductName}].
 
-[id="next-steps_installing-openshift-serverless"]
+[id="next-steps_install-serverless-operator"]
 == Next steps
 
-* After the {ServerlessOperatorName} is installed, you can install the Knative Serving component. See the documentation on xref:../../serverless/install/installing-knative-serving.adoc#installing-knative-serving[Installing Knative Serving].
-* After the {ServerlessOperatorName} is installed, you can install the Knative Eventing component. See the documentation on xref:../../serverless/install/installing-knative-eventing.adoc#installing-knative-eventing[Installing Knative Eventing].
+* After the {ServerlessOperatorName} is installed, you can xref:../../serverless/install/installing-knative-serving.adoc#installing-knative-serving[install Knative Serving] or xref:../../serverless/install/installing-knative-eventing.adoc#installing-knative-eventing[install Knative Eventing].
diff --git a/serverless/install/installing-knative-eventing.adoc b/serverless/install/installing-knative-eventing.adoc
@@ -1,8 +1,8 @@
 :_content-type: ASSEMBLY
-include::modules/serverless-document-attributes.adoc[]
 [id="installing-knative-eventing"]
 = Installing Knative Eventing
 include::modules/common-attributes.adoc[]
+include::modules/serverless-document-attributes.adoc[]
 :context: installing-knative-eventing
 
 toc::[]
@@ -11,11 +11,5 @@ After you install the {ServerlessOperatorName}, you can install Knative Eventing
 
 This guide provides information about installing Knative Eventing using the default settings.
 
-[id="prerequisites_installing-knative-eventing"]
-== Prerequisites
-
-* You have access to an {product-title} account with cluster administrator access.
-* You have installed {ServerlessOperatorName}.
-
 include::modules/serverless-install-eventing-web-console.adoc[leveloffset=+1]
 include::modules/serverless-install-eventing-yaml.adoc[leveloffset=+1]
diff --git a/serverless/install/installing-knative-serving.adoc b/serverless/install/installing-knative-serving.adoc
@@ -1,21 +1,13 @@
 :_content-type: ASSEMBLY
-include::modules/serverless-document-attributes.adoc[]
 [id="installing-knative-serving"]
 = Installing Knative Serving
 include::modules/common-attributes.adoc[]
+include::modules/serverless-document-attributes.adoc[]
 :context: installing-knative-serving
 
 toc::[]
 
-After you have xref:../../serverless/install/install-serverless-operator.adoc#install-serverless-operator[installed the {ServerlessOperatorName}], you can install Knative Serving.
-
-This guide provides information about installing Knative Serving using the default settings. However, you can configure more advanced settings in the `KnativeServing` custom resource definition (CRD). For more information about configuration options for the `KnativeServing` CRD, see xref:../../serverless/install/installing-knative-serving.adoc#knative-serving-advanced-config_installing-knative-serving[Knative Serving advanced configuration options].
-
-[id="prerequisites_installing-knative-serving"]
-== Prerequisites
-
-* You have access to an {product-title} account with cluster administrator access.
-* You have installed the {ServerlessOperatorName}.
+This guide provides information about installing Knative Serving using the default settings. However, you can configure more advanced settings in the `KnativeServing` custom resource (CR). For more information about configuration options for the `KnativeServing` CR, see xref:../../serverless/install/installing-knative-serving.adoc#knative-serving-advanced-config_installing-knative-serving[Advanced configuration options].
 
 include::modules/serverless-install-serving-web-console.adoc[leveloffset=+1]
 include::modules/serverless-install-serving-yaml.adoc[leveloffset=+1]
@@ -24,4 +16,4 @@ include::modules/knative-serving-advanced-config.adoc[leveloffset=+1]
 [id="next-steps_installing-knative-serving"]
 == Next steps
 
-* For cloud events functionality on {ServerlessProductName}, you can install the Knative Eventing component. See the documentation on xref:../../serverless/install/installing-knative-eventing.adoc#installing-knative-eventing[Installing Knative Eventing].
+* If you want to use Knative event-driven architecture you can xref:../../serverless/install/installing-knative-eventing.adoc#installing-knative-eventing[install Knative Eventing].
diff --git a/serverless/install/removing-openshift-serverless.adoc b/serverless/install/removing-openshift-serverless.adoc
diff --git a/serverless/serverless-update.adoc b/serverless/serverless-update.adoc
