SRVCOM-1728: Updating abstracts and other improvements for Jupiter guidelines in eventing docs

Author: abrennan89

modules/serverless-connect-sink-source-odc.adoc

@@ -7,14 +7,14 @@
 [id="serverless-connect-sink-source-odc_{context}"]
 = Connect an event source to a sink using the Developer perspective
 
-You can create multiple event source types in {product-title} that can be connected to sinks.
+When you create an event source by using the {product-title} web console, you can specify a sink where events are sent to from that resource. The sink can be any addressable or callable resource that can receive incoming events from other resources.
 
 .Prerequisites
 
 * The {ServerlessOperatorName}, Knative Serving, and Knative Eventing are installed on your {product-title} cluster.
-* You have created a sink.
 * You have logged in to the web console and are in the *Developer* perspective.
 * 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}.
+* You have created a sink, such as a Knative service, channel or broker.
 
 .Procedure
 

modules/serverless-connect-trigger-sink.adoc

@@ -6,9 +6,9 @@
 [id="serverless-connect-trigger-sink_{context}"]
 = Connecting a trigger to a sink
 
-You can connect a trigger to a sink, so that events from a broker are filtered before they are sent to the sink. A sink that is connected to a trigger is configured as a `subscriber` in the `Trigger` resource spec.
+You can connect a trigger to a sink, so that events from a broker are filtered before they are sent to the sink. A sink that is connected to a trigger is configured as a `subscriber` in the `Trigger` object's resource spec.
 
-.Example of a trigger connected to a Kafka sink
+.Example of a `Trigger` object connected to a Kafka sink
 [source,yaml]
 ----
 apiVersion: eventing.knative.dev/v1

modules/serverless-event-delivery-parameters.adoc

@@ -2,11 +2,13 @@
 //
 // serverless/develop/serverless-event-delivery.adoc
 
-:_content-type: CONCEPT
+:_content-type: REFERENCE
 [id="serverless-event-delivery-parameters_{context}"]
 = Configurable event delivery parameters
 
-The following parameters can be configured for event delivery.
+Knative Eventing provides configuration parameters that can be used to control what happens to events in cases where events fail to be delivered. For example, you can configure Knative to retry sending events that failed to be consumed, or forward these events to a dead letter sink.
+
+The following parameters can be configured for event delivery:
 
 Dead letter sink:: You can configure the `deadLetterSink` delivery parameter so that if an event fails to be delivered it is sent to the specified event sink.
 

modules/serverless-list-source-types-kn.adoc

@@ -6,16 +6,15 @@
 [id="serverless-list-source-types-kn_{context}"]
 = Listing available event source types by using the Knative CLI
 
-You can list event source types that can be created and used on your cluster by using the `kn source list-types` CLI command.
+Using the `kn` CLI provides a streamlined and intuitive user interface to view available event source types on your cluster. You can list event source types that can be created and used on your cluster by using the `kn source list-types` CLI command.
 
 .Prerequisites
 
 * The {ServerlessOperatorName} and Knative Eventing are installed on the cluster.
-* You have installed the `kn` CLI.
+* You have installed the Knative (`kn`) CLI.
 
 .Procedure
 
-ifdef::openshift-enterprise[]
 . List the available event source types in the terminal:
 +
 [source,terminal]
@@ -32,29 +31,12 @@ PingSource        pingsources.sources.knative.dev                 Periodically s
 SinkBinding       sinkbindings.sources.knative.dev                Binding for connecting a PodSpecable to a sink
 ----
 
+ifdef::openshift-enterprise[]
 . Optional: You can also list the available event source types in YAML format:
 +
 [source,terminal]
 ----
 $ kn source list-types -o yaml
 ----
 endif::[]
-// optional step not allowed yet for OSD due to upstream CLI issue #1385
-
-ifdef::openshift-dedicated[]
-* List the available event source types in the terminal:
-+
-[source,terminal]
-----
-$ kn source list-types
-----
-+
-.Example output
-[source,terminal]
-----
-TYPE              NAME                                            DESCRIPTION
-ApiServerSource   apiserversources.sources.knative.dev            Watch and send Kubernetes API events to a sink
-PingSource        pingsources.sources.knative.dev                 Periodically send ping events to a sink
-SinkBinding       sinkbindings.sources.knative.dev                Binding for connecting a PodSpecable to a sink
-----
-endif::[]
+// optional step not allowed yet for OSD due to upstream https://github.com/knative/client/issues/1385

modules/serverless-list-source-types-odc.adoc

@@ -6,7 +6,7 @@
 [id="serverless-list-source-types-odc_{context}"]
 = Viewing available event source types within the Developer perspective
 
-You can use the web console to view available event source types.
+It is possible to view a list of all available event source types on your cluster. Using the {product-title} web console provides a streamlined and intuitive user interface to view available event source types.
 
 .Prerequisites
 

modules/serverless-list-source.adoc

@@ -6,13 +6,22 @@
 [id="serverless-list-source_{context}"]
 = Listing available event sources by using the Knative CLI
 
-You can list available event sources by using the `kn source list` command.
+Using the `kn` CLI provides a streamlined and intuitive user interface to view existing event sources on your cluster. You can list existing event sources by using the `kn source list` command.
 
+.Prerequisites
+
+* The {ServerlessOperatorName} and Knative Eventing are installed on the cluster.
+* You have installed the Knative (`kn`) CLI.
+
+.Procedure
+
+. List the existing event sources in the terminal:
++
 [source,terminal]
 ----
 $ kn source list
 ----
-
++
 .Example output
 [source,terminal]
 ----
@@ -22,22 +31,19 @@ b1     SinkBinding       sinkbindings.sources.knative.dev       ksvc:eshow3   Fa
 p1     PingSource        pingsources.sources.knative.dev        ksvc:eshow1   True
 ----
 
-[id="serverless-list-source-specific-type_{context}"]
-== Listing event sources of a specific type only
-
-You can list event sources of a specific type only, by using the `--type` flag.
-
+. Optional: You can list event sources of a specific type only, by using the `--type` flag:
++
 [source,terminal]
 ----
 $ kn source list --type <event_source_type>
 ----
-
++
 .Example command
 [source,terminal]
 ----
 $ kn source list --type PingSource
 ----
-
++
 .Example output
 [source,terminal]
 ----

modules/serverless-subscription-event-delivery-config.adoc

@@ -7,9 +7,9 @@
 [id="serverless-subscription-event-delivery-config_{context}"]
 = Configuring event delivery failure parameters using subscriptions
 
-Developers 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 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.
 
-.Example subscription YAML
+.Example `Subscription` object
 [source,yaml]
 ----
 apiVersion: messaging.knative.dev/v1

modules/specifying-sink-flag-kn.adoc

@@ -8,13 +8,13 @@
 
 :_content-type: REFERENCE
 [id="specifying-sink-flag-kn_{context}"]
-= Knative CLI --sink flag
+= Knative CLI sink flag
 
-When you create an event-producing custom resource by using the Knative (`kn`) CLI, you can specify a sink where events are sent to from that resource, by using the `--sink` flag.
+When you create an event source by using the Knative (`kn`) CLI, you can specify a sink where events are sent to from that resource by using the `--sink` flag. The sink can be any addressable or callable resource that can receive incoming events from other resources.
 
 The following example creates a sink binding that uses a service, `\http://event-display.svc.cluster.local`, as the sink:
 
-.Example command using the `--sink` flag
+.Example command using the sink flag
 [source,terminal]
 ----
 $ kn source binding create bind-heartbeat \
@@ -23,5 +23,4 @@ $ kn source binding create bind-heartbeat \
   --sink http://event-display.svc.cluster.local \ <1>
   --ce-override "sink=bound"
 ----
-
 <1> `svc` in `\http://event-display.svc.cluster.local` determines that the sink is a Knative service. Other default sink prefixes include `channel`, and `broker`.

serverless/develop/serverless-event-sinks.adoc

@@ -6,7 +6,11 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-A sink is an addressable custom resource (CR) that can receive incoming events from other resources. Knative services, channels, and brokers are all examples of sinks.
+When you create an event source, you can specify a sink where events are sent to from the source. A sink is an addressable or a callable resource that can receive incoming events from other resources. Knative services, channels and brokers are all examples of sinks.
+
+Addressable objects receive and acknowledge an event delivered over HTTP to an address defined in their `status.address.url` field. As a special case, the core Kubernetes `Service` object also fulfills the addressable interface.
+
+Callable objects are able to receive an event delivered over HTTP and transform the event, returning `0` or `1` new events in the HTTP response. These returned events may be further processed in the same way that events from an external event source are processed.
 
 // Using --sink flag with kn (generic)
 include::modules/specifying-sink-flag-kn.adoc[leveloffset=+1]

serverless/develop/serverless-listing-event-sources.adoc

@@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can use the `kn` CLI or the *Developer* perspective in the {product-title} web console to list and manage available event sources or event source types.
+It is possible to view a list of all event sources or event source types that exist or are available for use on your {product-title} cluster. You can use the `kn` CLI or the *Developer* perspective in the {product-title} web console to list available event sources or event source types.
 
 include::modules/serverless-list-source-types-kn.adoc[leveloffset=+1]
 include::modules/serverless-list-source-types-odc.adoc[leveloffset=+1]