Merge pull request #43288 from abrennan89/SRVCOM-1728

SRVCOM-1728: Update serverless abstracts to align with Jupiter requirements

Author: abrennan89

modules/about-knative-eventing.adoc

@@ -6,11 +6,9 @@
 [id="about-knative-eventing_{context}"]
 = Knative Eventing
 
-Knative Eventing on {product-title} enables developers to use an link:https://www.redhat.com/en/topics/integration/what-is-event-driven-architecture[event-driven architecture] with serverless applications.
+Knative Eventing on {product-title} enables developers to use an link:https://www.redhat.com/en/topics/integration/what-is-event-driven-architecture[event-driven architecture] with serverless applications. An event-driven architecture is based on the concept of decoupled relationships between event producers and event consumers.
 
-An event-driven architecture is based on the concept of decoupled relationships between event producers and event consumers. Event producers create events, and event _sinks_, or consumers, receive events.
-
-Knative Eventing uses standard HTTP POST requests to send and receive events between event producers and sinks. These events conform to the link:https://cloudevents.io[CloudEvents specifications], which enables creating, parsing, sending, and receiving events in any programming language.
+Event producers create events, and event _sinks_, or consumers, receive events. Knative Eventing uses standard HTTP POST requests to send and receive events between event producers and sinks. These events conform to the link:https://cloudevents.io[CloudEvents specifications], which enables creating, parsing, sending, and receiving events in any programming language.
 
 Knative Eventing supports the following use cases:
 

modules/about-knative-serving.adoc

@@ -6,9 +6,7 @@
 [id="about-knative-serving_{context}"]
 = Knative Serving
 
-Knative Serving on {product-title} enables developers to write link:https://www.redhat.com/en/topics/cloud-native-apps[cloud-native applications] using link:https://www.redhat.com/en/topics/cloud-native-apps/what-is-serverless[serverless architecture].
-
-Knative Serving supports deploying and managing cloud-native applications. It provides a set of objects as Kubernetes custom resource definitions (CRDs) that define and control the behavior of serverless workloads on an {product-title} cluster.
+Knative Serving supports developers who want to create, deploy, and manage link:https://www.redhat.com/en/topics/cloud-native-apps[cloud-native applications]. It provides a set of objects as Kubernetes custom resource definitions (CRDs) that define and control the behavior of serverless workloads on an {product-title} cluster.
 
 Developers use these CRDs to create custom resource (CR) instances that can be used as building blocks to address complex use cases. For example:
 

modules/serverless-api-versions.adoc

@@ -6,8 +6,8 @@
 [id="serverless-api-versions_{context}"]
 = About API versions
 
-The {ServerlessOperatorName} automatically upgrades older resources that use deprecated versions of APIs to use the latest version.
+API versions are an important measure of the development status of certain features and custom resources in {ServerlessProductName}. Creating resources on your cluster that do not use the correct API version can cause issues in your deployment.
 
-For example, if you have created resources on your cluster that use older versions of the `ApiServerSource` API, such as `v1beta1`, the {ServerlessOperatorName} automatically updates these resources to use the `v1` version of the API when this is available and the `v1beta1` version is deprecated.
+The {ServerlessOperatorName} automatically upgrades older resources that use deprecated versions of APIs to use the latest version. For example, if you have created resources on your cluster that use older versions of the `ApiServerSource` API, such as `v1beta1`, the {ServerlessOperatorName} automatically updates these resources to use the `v1` version of the API when this is available and the `v1beta1` version is deprecated.
 
 After they have been deprecated, older versions of APIs might be removed in any upcoming release. Using deprecated versions of APIs does not cause resources to fail. However, if you try to use a version of an API that has been removed, it will cause resources to fail. Ensure that your manifests are updated to use the latest version to avoid issues.

modules/serverless-cluster-sizing-req.adoc

@@ -6,13 +6,13 @@
 [id="serverless-cluster-sizing-req_{context}"]
 = Defining cluster size requirements
 
-To install and use {ServerlessProductName}, the {product-title} cluster must be sized correctly.
+To install and use {ServerlessProductName}, the {product-title} cluster must be sized correctly. The total size requirements to run {ServerlessProductName} are dependent on the components that are installed and the applications that are deployed, and might vary depending on your deployment.
 
 [NOTE]
 ====
 The following requirements relate only to the pool of worker machines of the {product-title} cluster. Control plane nodes are not used for general scheduling and are omitted from the requirements.
 ====
 
-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.
+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.

modules/serverless-install-web-console.adoc

@@ -6,7 +6,7 @@
 [id="serverless-install-web-console_{context}"]
 = Installing the {ServerlessOperatorName}
 
-This procedure describes how to install and subscribe to the {ServerlessOperatorName} from the OperatorHub by using the {product-title} web console.
+You can install the {ServerlessOperatorName} from the OperatorHub by using the {product-title} web console. Installing this Operator enables you to install and use Knative components.
 
 .Prerequisites
 
@@ -32,7 +32,7 @@ endif::[]
 
 .. 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`.
+.. The *Installed Namespace* is `openshift-serverless`.
 
 .. Select the *stable* channel as the *Update Channel*. The *stable* channel will enable installation of the latest stable release of the {ServerlessOperatorName}.
 

serverless/discover/about-serverless.adoc

@@ -7,11 +7,7 @@ include::_attributes/serverless-document-attributes.adoc[]
 
 toc::[]
 
-{ServerlessProductName} simplifies the process of delivering code from development into production by reducing the need for infrastructure set up or back-end development by developers.
-
-Developers on {ServerlessProductName} can use the provided Kubernetes native APIs (Knative Serving and Eventing), as well as familiar languages and frameworks, to deploy applications and container workloads.
-
-{ServerlessProductName} is based on the open source link:https://knative.dev/docs/[Knative project], which provides portability and consistency for hybrid and multi-cloud environments by enabling an enterprise-grade serverless platform.
+{ServerlessProductName} provides Kubernetes native building blocks that enable developers to create and deploy serverless, event-driven applications on {product-title}. {ServerlessProductName} is based on the open source link:https://knative.dev/docs/[Knative project], which provides portability and consistency for hybrid and multi-cloud environments by enabling an enterprise-grade serverless platform.
 
 // Knative Serving
 include::modules/about-knative-serving.adoc[leveloffset=+1]
@@ -21,8 +17,8 @@ include::modules/about-knative-eventing.adoc[leveloffset=+1]
 
 You can propagate an event from an xref:../../serverless/discover/knative-event-sources.adoc#knative-event-sources[event source] to multiple event sinks by using:
 
-* xref:../../serverless/discover/serverless-channels.adoc#serverless-channels[channels] and subscriptions, or
-* xref:../../serverless/develop/serverless-using-brokers.adoc#serverless-using-brokers[brokers] and xref:../../serverless/develop/serverless-triggers.adoc#serverless-triggers[triggers].
+* xref:../../serverless/discover/serverless-channels.adoc#serverless-channels[Channels and subscriptions], or
+* xref:../../serverless/develop/serverless-using-brokers.adoc#serverless-using-brokers[Brokers] and xref:../../serverless/develop/serverless-triggers.adoc#serverless-triggers[Triggers].
 
 // add something about CLI tools?
 
@@ -32,12 +28,11 @@ You can propagate an event from an xref:../../serverless/discover/knative-event-
 The set of supported features, configurations, and integrations for {ServerlessProductName}, current and past versions, are available at the link:https://access.redhat.com/articles/4912821[Supported Configurations page].
 
 // only included for OCP currently until CRD docs are available in OSD
-ifdef::openshift-online[]
+ifdef::openshift-enterprise[]
 [id="additional-resources_about-serverless"]
 [role="_additional-resources"]
 == Additional resources
-
-* For more information about CRDs, see xref:../../operators/understanding/crds/crd-extending-api-with-crds.adoc#crd-extending-api-with-crds[Extending the Kubernetes API with custom resource definitions].
-
-* For more information about CRs, see xref:../../operators/understanding/crds/crd-managing-resources-from-crds.adoc#crd-managing-resources-from-crds[Managing resources from custom resource definitions].
+* xref:../../operators/understanding/crds/crd-extending-api-with-crds.adoc#crd-extending-api-with-crds[Extending the Kubernetes API with custom resource definitions]
+* xref:../../operators/understanding/crds/crd-managing-resources-from-crds.adoc#crd-managing-resources-from-crds[Managing resources from custom resource definitions]
 endif::[]
+* link:https://www.redhat.com/en/topics/cloud-native-apps/what-is-serverless[What is serverless?]

serverless/discover/serverless-functions-about.adoc

@@ -7,13 +7,11 @@ include::_attributes/serverless-document-attributes.adoc[]
 
 toc::[]
 
+{FunctionsProductName} enables developers to create and deploy stateless, event-driven functions as a Knative service on {product-title}. The `kn func` CLI is provided as a plug-in for the Knative `kn` CLI. {FunctionsProductName} uses the link:https://buildpacks.io/[CNCF Buildpack API] to create container images. After a container image is created, you can use the `kn func` CLI to deploy the container image as a Knative service on the cluster.
+
 :FeatureName: {FunctionsProductName}
 include::snippets/technology-preview.adoc[leveloffset=+2]
 
-{FunctionsProductName} enables developers to create and deploy stateless, event-driven functions as a Knative service on {product-title}.
-
-The `kn func` CLI is provided as a plug-in for the Knative `kn` CLI. {FunctionsProductName} uses the link:https://buildpacks.io/[CNCF Buildpack API] to create container images. After a container image has been created, you can use the `kn func` CLI to deploy the container image as a Knative service on the cluster.
-
 [id="serverless-functions-about-runtimes"]
 == Supported runtimes
 
@@ -29,4 +27,4 @@ The `kn func` CLI is provided as a plug-in for the Knative `kn` CLI. {FunctionsP
 [id="next-steps_serverless-functions-about"]
 == Next steps
 
-* See xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-functions-getting-started[Getting started with functions].
+* xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-functions-getting-started[Getting started with functions].

serverless/install/install-serverless-operator.adoc

@@ -7,8 +7,9 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can install the {ServerlessOperatorName} to an {product-title} cluster by following the procedures in this document.
+Installing the {ServerlessOperatorName} enables you to install and use Knative Serving, Knative Eventing, and Knative Kafka on a {product-title} cluster. The {ServerlessOperatorName} manages Knative custom resource definitions (CRDs) for your cluster and enables you to configure them without directly modifying individual config maps for each component.
 
+// OCP specific docs
 ifdef::openshift-enterprise[]
 [id="install-serverless-operator-before-you-begin"]
 == Before you begin
@@ -20,21 +21,22 @@ Read the following information about supported configurations and prerequisites
 * {ServerlessProductName} currently cannot be used in a multi-tenant configuration on a single cluster.
 
 include::modules/serverless-cluster-sizing-req.adoc[leveloffset=+2]
-endif::[]
 
-ifdef::openshift-dedicated[]
-include::modules/serverless-cluster-sizing-req.adoc[leveloffset=+1]
-endif::[]
-
-ifdef::openshift-enterprise[]
 [id="install-serverless-operator-scaling-with-machinesets"]
 === Scaling your cluster using machine sets
 
 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].
-endif::[]
+
 // TODO: Add OSD specific docs for auto scaling machine sets? These docs aren't available for OSD so we need to look into what's required to doc here.
 // QE thread related: https://coreos.slack.com/archives/CD87JDUB0/p1643986092796179
+endif::[]
+
+// OSD docs
+ifdef::openshift-dedicated[]
+include::modules/serverless-cluster-sizing-req.adoc[leveloffset=+1]
+endif::[]
 
+// universal install doc
 include::modules/serverless-install-web-console.adoc[leveloffset=+1]
 
 [id="additional-resources_install-serverless-operator"]

serverless/serverless-release-notes.adoc

@@ -7,7 +7,7 @@ include::_attributes/serverless-document-attributes.adoc[]
 
 toc::[]
 
-This topic includes information about new features, changes, and known issues that pertain to the latest {ServerlessProductName} release on {product-title}.
+Release notes contain information about new and deprecated features, breaking changes, and known issues. The following release notes apply for the most recent {ServerlessProductName} releases on {product-title}.
 
 For an overview of {ServerlessProductName} functionality, see xref:../serverless/discover/about-serverless.adoc#about-serverless[About {ServerlessProductName}].