SRCOM-1728: Updated channel and subs abstracts, introduction content

abrennan89 · abrennan89 · commit 46fa53c398ff · 2022-04-12T14:14:42.000-05:00
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -2216,7 +2216,7 @@ Topics:
   Distros: openshift-webscale
 - Name: Workload partitioning on single node OpenShift
   File: sno-du-enabling-workload-partitioning-on-single-node-openshift
-  Distros: openshift-origin,openshift-enterprise  
+  Distros: openshift-origin,openshift-enterprise
 - Name: Deploying distributed units at scale in a disconnected environment
   File: ztp-deploying-disconnected
   Distros: openshift-origin,openshift-enterprise
@@ -3418,7 +3418,7 @@ Topics:
     Name: Custom event sources
   - Name: Creating channels
     File: serverless-creating-channels
-  - Name: Creating subscriptions
+  - Name: Creating and managing subscriptions
     File: serverless-subs
 # Brokers
   - Name: Brokers
diff --git a/_topic_maps/_topic_map_osd.yml b/_topic_maps/_topic_map_osd.yml
@@ -264,7 +264,7 @@ Topics:
     Name: Custom event sources
   - Name: Creating channels
     File: serverless-creating-channels
-  - Name: Creating subscriptions
+  - Name: Creating and managing subscriptions
     File: serverless-subs
   - Name: Brokers
     File: serverless-using-brokers
diff --git a/modules/serverless-create-channel-kn.adoc b/modules/serverless-create-channel-kn.adoc
@@ -6,12 +6,12 @@
 [id="serverless-create-channel-kn_{context}"]
 = Creating a channel by using the Knative CLI
 
-You can create a channel with the cluster default configuration by using the `kn` CLI.
+Using the `kn` CLI to create channels provides a more streamlined and intuitive user interface than modifying YAML files directly. You can use the `kn channel create` command to create a channel by using the `kn` CLI.
 
 .Prerequisites
 
 * The {ServerlessOperatorName} and Knative Eventing are installed on the cluster.
-* You have installed the `kn` CLI.
+* You have installed the Knative (`kn`) CLI.
 * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
 
 .Procedure
@@ -55,7 +55,7 @@ mychannel   InMemoryChannel   http://mychannel-kn-channel.default.svc.cluster.lo
 ----
 
 .Deleting a channel
-
+// split into own module, out of scope for this PR
 * Delete a channel:
 +
 [source,terminal]
diff --git a/modules/serverless-create-channel-odc.adoc b/modules/serverless-create-channel-odc.adoc
@@ -6,7 +6,7 @@
 [id="serverless-create-channel-odc_{context}"]
 = Creating a channel by using the web console
 
-You can create a channel by using the {product-title} web console.
+Using the {product-title} web console provides a streamlined and intuitive user interface to create a channel. After Knative Eventing is installed on your cluster, you can create a channel by using the web console.
 
 .Prerequisites
 
diff --git a/modules/serverless-create-default-channel-yaml.adoc b/modules/serverless-create-default-channel-yaml.adoc
@@ -6,12 +6,12 @@
 [id="serverless-create-default-channel-yaml_{context}"]
 = Creating a default implementation channel by using YAML
 
-You can create a channel with the cluster default configuration by using YAML.
+Creating Knative resources by using YAML files uses a declarative API, which enables you to describe channels declaratively and in a reproducible manner. To create a serverless channel by using YAML, you must create a YAML file that defines a `Channel` object, then apply it by using the `oc apply` command.
 
 .Prerequisites
 
 * The {ServerlessOperatorName} and Knative Eventing are installed on the cluster.
-* Install the OpenShift CLI (`oc`).
+* Install the OpenShift (`oc`) CLI.
 * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
 
 .Procedure
diff --git a/modules/serverless-create-kafka-channel-yaml.adoc b/modules/serverless-create-kafka-channel-yaml.adoc
@@ -7,12 +7,12 @@
 [id="serverless-create-kafka-channel-yaml_{context}"]
 = Creating a Kafka channel by using YAML
 
-You can create a Knative Eventing channel that is backed by Kafka topics. To do this, you must create a `KafkaChannel` object. The following procedure explains how you can create a `KafkaChannel` object by using YAML files and the `oc` CLI.
+Creating Knative resources by using YAML files uses a declarative API, which enables you to describe channels declaratively and in a reproducible manner. You can create a Knative Eventing channel that is backed by Kafka topics by creating a Kafka channel. To create a Kafka channel by using YAML, you must create a YAML file that defines a `KafkaChannel` object, then apply it by using the `oc apply` command.
 
 .Prerequisites
 
 * The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` custom resource are installed on your {product-title} cluster.
-* Install the OpenShift CLI (`oc`).
+* Install the OpenShift (`oc`) CLI.
 * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
 
 .Procedure
diff --git a/modules/serverless-creating-subscriptions-kn.adoc b/modules/serverless-creating-subscriptions-kn.adoc
@@ -6,12 +6,12 @@
 [id="serverless-creating-subscriptions-kn_{context}"]
 = Creating a subscription by using the Knative CLI
 
-You can create a subscription to connect a channel to a sink by using the `kn` CLI.
+After you have created a channel and an event sink, you can create a subscription to enable event delivery. Using the `kn` CLI to create subscriptions provides a more streamlined and intuitive user interface than modifying YAML files directly. You can use the `kn subscription create` command as well as the appropriate flags to create a subscription by using the `kn` CLI.
 
 .Prerequisites
 
 * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster.
-* You have installed the `kn` CLI.
+* You have installed the Knative (`kn`) CLI.
 * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
 
 .Procedure
@@ -61,7 +61,7 @@ mysubscription   Channel:mychannel   ksvc:event-display
 ----
 
 .Deleting a subscription
-
+// move to own procedure, out of scope for this PR
 * Delete a subscription:
 +
 [source,terminal]
diff --git a/modules/serverless-creating-subscriptions-odc.adoc b/modules/serverless-creating-subscriptions-odc.adoc
@@ -6,7 +6,7 @@
 [id="serverless-creating-subscriptions-odc_{context}"]
 = Creating a subscription by using the web console
 
-You can create a subscription to connect a channel to a sink by using the {product-title} web console.
+After you have created a channel and an event sink, you can create a subscription to enable event delivery. Using the {product-title} web console provides a streamlined and intuitive user interface to create a subscription.
 
 .Prerequisites
 
diff --git a/modules/serverless-creating-subscriptions-yaml.adoc b/modules/serverless-creating-subscriptions-yaml.adoc
@@ -6,12 +6,12 @@
 [id="serverless-creating-subscriptions-yaml_{context}"]
 = Creating a subscription by using YAML
 
-You can create a subscription to connect a channel to a sink by using YAML.
+After you have created a channel and an event sink, you can create a subscription to enable event delivery. Creating Knative resources by using YAML files uses a declarative API, which enables you to describe subscriptions declaratively and in a reproducible manner. To create a subscription by using YAML, you must create a YAML file that defines a `Subscription` object, then apply it by using the `oc apply` command.
 
 .Prerequisites
 
 * The {ServerlessOperatorName} and Knative Eventing are installed on the cluster.
-* Install the OpenShift CLI (`oc`).
+* Install the OpenShift (`oc`) CLI.
 * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
 
 .Procedure
diff --git a/modules/serverless-describe-subs-kn.adoc b/modules/serverless-describe-subs-kn.adoc
@@ -6,11 +6,11 @@
 [id="serverless-describe-subs-kn_{context}"]
 = Describing subscriptions by using the Knative CLI
 
-You can print information about a subscription in the terminal by using the `kn` CLI.
+You can use the `kn subscription describe` command to print information about a subscription in the terminal by using the `kn` CLI. Using the `kn` CLI to describe subscriptions provides a more streamlined and intuitive user interface than viewing YAML files directly.
 
 .Prerequisites
 
-* You have installed the `kn` CLI.
+* You have installed the Knative (`kn`) CLI.
 * You have created a subscription in your cluster.
 
 .Procedure
diff --git a/modules/serverless-list-subs-kn.adoc b/modules/serverless-list-subs-kn.adoc
@@ -6,11 +6,11 @@
 [id="serverless-list-subs-kn_{context}"]
 = Listing subscriptions by using the Knative CLI
 
-You can list existing subscriptions on your cluster by using the `kn` CLI.
+You can use the `kn subscription list` command to list existing subscriptions on your cluster by using the `kn` CLI. Using the `kn` CLI to list subscriptions provides a streamlined and intuitive user interface.
 
 .Prerequisites
 
-* You have installed the `kn` CLI.
+* You have installed the Knative (`kn`) CLI.
 
 .Procedure
 
diff --git a/modules/serverless-subscription-event-delivery-config.adoc b/modules/serverless-subscription-event-delivery-config.adoc
@@ -7,7 +7,7 @@
 [id="serverless-subscription-event-delivery-config_{context}"]
 = Configuring event delivery failure parameters using subscriptions
 
-Knative Eventing provides configuration parameters for subscriptions that can be used to control what happens to events in cases where events fail to be delivered. You can configure event delivery parameters for individual subscriptions by modifying the `delivery` settings for a `Subscription` object.
+After you have created a channel and an event sink, you can create a subscription to enable event delivery. You can configure event delivery parameters for individual subscriptions by modifying the `delivery` settings for a `Subscription` object. Knative Eventing provides configuration parameters for subscriptions that you can use to control what happens to events in cases where events fail to be delivered.
 
 .Example `Subscription` object
 [source,yaml]
diff --git a/modules/serverless-update-subscriptions-kn.adoc b/modules/serverless-update-subscriptions-kn.adoc
@@ -6,11 +6,11 @@
 [id="serverless-update-subscriptions-kn_{context}"]
 = Updating subscriptions by using the Knative CLI
 
-You can update a subscription by using the `kn` CLI.
+You can use the `kn subscription update` command as well as the appropriate flags to update a subscription from the terminal by using the `kn` CLI. Using the `kn` CLI to update subscriptions provides a more streamlined and intuitive user interface than updating YAML files directly.
 
 .Prerequisites
 
-* You have installed the `kn` CLI.
+* You have installed the Knative (`kn`) CLI.
 * You have created a subscription.
 
 .Procedure
diff --git a/serverless/develop/serverless-creating-channels.adoc b/serverless/develop/serverless-creating-channels.adoc
@@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can use the following procedures to create channels.
+include::snippets/serverless-channels-intro.adoc[]
 
 include::modules/serverless-create-channel-odc.adoc[leveloffset=+1]
 include::modules/serverless-create-channel-kn.adoc[leveloffset=+1]
diff --git a/serverless/develop/serverless-subs.adoc b/serverless/develop/serverless-subs.adoc
@@ -1,12 +1,12 @@
 :_content-type: ASSEMBLY
 [id="serverless-subs"]
-= Creating subscriptions
+= Creating and managing subscriptions
 include::_attributes/common-attributes.adoc[]
 :context: serverless-subs
 
 toc::[]
 
-You can use the following procedures to create subscriptions that allow event sinks to subscribe to channels and receive events.
+After you have created a channel and an event sink, you can create a subscription to enable event delivery. Subscriptions are created by configuring a `Subscription` object, which specifies the channel and the sink (also known as a _subscriber_) to deliver events to. You can also specify some sink-specific options, such as how to handle failures.
 
 include::modules/serverless-creating-subscriptions-odc.adoc[leveloffset=+1]
 include::modules/serverless-creating-subscriptions-yaml.adoc[leveloffset=+1]
diff --git a/serverless/discover/serverless-channels.adoc b/serverless/discover/serverless-channels.adoc
@@ -6,11 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Channels are custom resources that define a single event-forwarding and persistence layer. After events have been sent to a channel from an event source or producer, these events can be sent to multiple Knative services, or other sinks, by using a subscription.
-
-image::serverless-event-channel-workflow.png[Channel workflow overview]
-
-You can create channels by instantiating a supported `Channel` object, and configure xref:../../serverless/develop/serverless-event-delivery.adoc#serverless-event-delivery[re-delivery attempts] by modifying the `delivery` spec in a `Subscription` object.
+include::snippets/serverless-channels-intro.adoc[]
 
 After you create a `Channel` object, a mutating admission webhook adds a set of `spec.channelTemplate` properties for the `Channel` object based on the default channel implementation. For example, for an `InMemoryChannel` default implementation, the `Channel` object looks as follows:
 
diff --git a/snippets/serverless-channels-intro.adoc b/snippets/serverless-channels-intro.adoc
@@ -0,0 +1,10 @@
+// Text snippet included in the following files
+//
+// * /serverless/develop/serverless-creating-channels.adoc
+// * /serverless/discover/serverless-channels.adoc
+
+Channels are custom resources that define a single event-forwarding and persistence layer. After events have been sent to a channel from an event source or producer, these events can be sent to multiple Knative services or other sinks by using a subscription.
+
+image::serverless-event-channel-workflow.png[Channel workflow overview]
+
+You can create channels by instantiating a supported `Channel` object, and configure xref:../../serverless/develop/serverless-event-delivery.adoc#serverless-event-delivery[re-delivery attempts] by modifying the `delivery` spec in a `Subscription` object.
