Merge pull request #44337 from abrennan89/abstracts2

abrennan89 · web-flow · commit 77ec5cd1e430 · 2022-04-12T15:18:13.000-05:00
SRVCOM-1728: Update abstracts for event source docs to use Jupiter guidelines, other misc. improvements
diff --git a/modules/apiserversource-kn.adoc b/modules/apiserversource-kn.adoc
@@ -7,25 +7,26 @@
 [id="apiserversource-kn_{context}"]
 = Creating an API server source by using the Knative CLI
 
-You can use the following procedure to create an API server source by using the `kn` CLI.
+You can use the `kn source apiserver create` command to create an API server source by using the `kn` CLI. Using the `kn` CLI to create an API server source provides a more streamlined and intuitive user interface than modifying YAML files directly. 
 
 .Prerequisites
 
 * The {ServerlessOperatorName} and Knative Eventing are installed on the cluster.
 * 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 installed the `oc` CLI.
-* You have installed the `kn` CLI.
+* You have installed the OpenShift (`oc`) CLI.
+* You have installed the Knative (`kn`) CLI.
 
 .Procedure
 
 include::snippets/serverless-service-account-apiserversource.adoc[]
 
-. Create an API server source that uses a broker as a sink:
+. Create an API server source that has an event sink. In the following example, the sink is a broker:
 +
 [source,terminal]
 ----
 $ kn source apiserver create <event_source_name> --sink broker:<broker_name> --resource "event:v1" --service-account <service_account_name> --mode Resource
 ----
+// need to revisit these docs and give better tutorial examples with different sinks; out of scope for the current PR
 
 . To check that the API server source is set up correctly, create a Knative service that dumps incoming messages to its log:
 +
@@ -34,7 +35,7 @@ $ kn source apiserver create <event_source_name> --sink broker:<broker_name> --r
 $ kn service create <service_name> --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest
 ----
 
-. Create a trigger to filter events from the `default` broker to the service:
+. If you used a broker as an event sink, create a trigger to filter events from the `default` broker to the service:
 +
 [source,terminal]
 ----
diff --git a/modules/apiserversource-yaml.adoc b/modules/apiserversource-yaml.adoc
@@ -6,14 +6,14 @@
 [id="apiserversource-yaml_context"]
 = Creating an API server source by using YAML files
 
-You can use the following procedure to create an API server source by using YAML files.
+Creating Knative resources by using YAML files uses a declarative API, which enables you to describe event sources declaratively and in a reproducible manner. To create an API server source by using YAML, you must create a YAML file that defines an `ApiServerSource` object, then apply it by using the `oc apply` command.
 
 .Prerequisites
 
 * The {ServerlessOperatorName} and Knative Eventing are installed on the cluster.
 * 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 the `default` broker in the same namespace as the one defined in the API server source YAML file.
-* Install the OpenShift CLI (`oc`).
+* Install the OpenShift (`oc`) CLI.
 
 .Procedure
 
diff --git a/modules/odc-creating-apiserversource.adoc b/modules/odc-creating-apiserversource.adoc
@@ -6,14 +6,14 @@
 [id="odc-creating-apiserversource_{context}"]
 = Creating an API server source by using the web console
 
-You can use the following procedure to create an API server source by using the {product-title} web console.
+After Knative Eventing is installed on your cluster, you can create an API server source by using the web console. Using the {product-title} web console provides a streamlined and intuitive user interface to create an event source. 
 
 .Prerequisites
 
 * You have logged in to the {product-title} web console.
 * The {ServerlessOperatorName} and Knative Eventing are installed on the cluster.
 * 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 installed the `oc` CLI.
+* You have installed the OpenShift (`oc`) CLI.
 
 .Procedure
 
diff --git a/modules/serverless-containersource-guidelines.adoc b/modules/serverless-containersource-guidelines.adoc
@@ -6,12 +6,9 @@
 [id="serverless-containersource-guidelines_{context}"]
 = Guidelines for creating a container image
 
-* Two environment variables are injected by the container source controller: `K_SINK` and `K_CE_OVERRIDES`. These variables are resolved from the `sink` and `ceOverrides` spec, respectively.
+Two environment variables are injected by the container source controller: `K_SINK` and `K_CE_OVERRIDES`. These variables are resolved from the `sink` and `ceOverrides` spec, respectively. Events are sent to the sink URI specified in the `K_SINK` environment variable. The message must be sent as a `POST` using the link:https://cloudevents.io/[`CloudEvent`] HTTP format.
 
-* Event messages are sent to the sink URI specified in the `K_SINK` environment variable. The event message can be in any format; however, using the link:https://cloudevents.io/[`CloudEvent`] spec is recommended.
-
-[id="serverless-containersource-guidelines-examples_{context}"]
-== Example container images
+.Example container images
 
 The following is an example of a heartbeats container image:
 
diff --git a/modules/serverless-containersource-reference.adoc b/modules/serverless-containersource-reference.adoc
@@ -6,8 +6,7 @@
 [id="serverless-containersource-reference_{context}"]
 = Container source reference
 
-This topic provides reference information about the configurable fields for the
-`ContainerSource` object.
+You can use a container as an event source, by creating a `ContainerSource` object. You can configure multiple parameters when creating a `ContainerSource` object.
 
 `ContainerSource` objects support the following fields:
 
@@ -47,9 +46,7 @@ This topic provides reference information about the configurable fields for the
 
 |===
 
-[id="serverless-containersource-reference-template-parameter-example_{context}"]
-== Template parameter example
-
+.Template parameter example
 [source,yaml]
 ----
 apiVersion: sources.knative.dev/v1
@@ -75,7 +72,7 @@ spec:
 [id="serverless-containersource-reference-cloudevent-overrides_{context}"]
 == CloudEvent overrides
 
-A `ceOverrides` definition provides overrides that control the CloudEvent's output format and modifications sent to the sink
+A `ceOverrides` definition provides overrides that control the CloudEvent's output format and modifications sent to the sink. You can configure multiple fields for the `ceOverrides` definition.
 
 A `ceOverrides` definition supports the following fields:
 
diff --git a/modules/serverless-kn-containersource.adoc b/modules/serverless-kn-containersource.adoc
@@ -6,8 +6,9 @@
 :_content-type: REFERENCE
 [id="serverless-kn-containersource_{context}"]
 = Creating and managing container sources by using the Knative CLI
+// needs to be revised as separate procedure modules; out of scope for this PR
 
-You can use the following `kn` commands to create and manage container sources:
+You can use the `kn source container` commands to create  and manage container sources by using the `kn` CLI. Using the `kn` CLI to create event sources provides a more streamlined and intuitive user interface than modifying YAML files directly. 
 
 .Create a container source
 [source,terminal]
diff --git a/modules/serverless-odc-create-containersource.adoc b/modules/serverless-odc-create-containersource.adoc
@@ -6,7 +6,7 @@
 [id="serverless-odc-create-containersource_{context}"]
 = Creating a container source by using the web console
 
-You can create a container source by using the *Developer* perspective of the {product-title} web console.
+After Knative Eventing is installed on your cluster, you can create a container source by using the web console. Using the {product-title} web console provides a streamlined and intuitive user interface to create an event source.
 
 .Prerequisites
 
diff --git a/modules/serverless-pingsource-kn.adoc b/modules/serverless-pingsource-kn.adoc
@@ -7,13 +7,14 @@
 [id="serverless-pingsource-kn_{context}"]
 = Creating a ping source by using the Knative CLI
 
-You can use the following procedure to create a ping source by using the `kn` CLI.
+You can use the `kn source ping create` command to create a ping source by using the `kn` CLI. Using the `kn` CLI to create event sources provides a more streamlined and intuitive user interface than modifying YAML files directly.
 
 .Prerequisites
 
 * The {ServerlessOperatorName}, Knative Serving 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}.
+* Optional: If you want to use the verification steps for this procedure, install the OpenShift (`oc`) CLI.
 
 .Procedure
 
@@ -108,6 +109,7 @@ Data,
 ----
 
 .Deleting the ping source
+// move to a separate procedure, out of scope for this PR
 
 * Delete the ping source:
 +
diff --git a/modules/serverless-pingsource-odc.adoc b/modules/serverless-pingsource-odc.adoc
@@ -6,7 +6,7 @@
 [id="serverless-pingsource-odc_{context}"]
 = Creating a ping source by using the web console
 
-You can use the following procedure to create a ping source by using the {product-title} web console.
+After Knative Eventing is installed on your cluster, you can create a ping source by using the web console. Using the {product-title} web console provides a streamlined and intuitive user interface to create an event source.
 
 .Prerequisites
 
@@ -61,6 +61,7 @@ You can verify that the ping source was created and is connected to the sink by
 image::verify-pingsource-ODC.png[View the ping source and service in the Topology view]
 
 .Deleting the ping source
+// move to separate procedure, out of scope for this PR
 
 . Navigate to the *Topology* view.
 . Right-click the API server source and select *Delete Ping Source*.
diff --git a/modules/serverless-pingsource-yaml.adoc b/modules/serverless-pingsource-yaml.adoc
@@ -6,20 +6,41 @@
 [id="serverless-pingsource-yaml_{context}"]
 = Creating a ping source by using YAML
 
-The following sections describe how to create a basic ping source using YAML files.
+Creating Knative resources by using YAML files uses a declarative API, which enables you to describe event sources declaratively and in a reproducible manner. To create a serverless ping source by using YAML, you must create a YAML file that defines a `PingSource` object, then apply it by using `oc apply`.
+
+.Example `PingSource` object
+[source,yaml]
+----
+apiVersion: sources.knative.dev/v1alpha2
+kind: PingSource
+metadata:
+  name: test-ping-source
+spec:
+  schedule: "*/2 * * * *" <1>
+  jsonData: '{"message": "Hello world!"}' <2>
+  sink: <3>
+    ref:
+      apiVersion: serving.knative.dev/v1
+      kind: Service
+      name: event-display
+----
+
+<1> The schedule of the event specified using https://kubernetes.io/docs/tasks/job/automated-tasks-with-cron-jobs/#schedule[CRON expression].
+<2> The event message body expressed as a JSON encoded data string.
+<3> These are the details of the event consumer. In this example, we are using a Knative service named `event-display`.
 
 .Prerequisites
 
 * The {ServerlessOperatorName}, Knative Serving 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
 
 . To verify that the ping source is working, create a simple Knative
 service that dumps incoming messages to the service's logs.
 
-.. Copy the example YAML into a file named `service.yaml`:
+.. Create a service YAML file:
 +
 [source,yaml]
 ----
@@ -37,12 +58,12 @@ spec:
 +
 [source,terminal]
 ----
-$ oc apply --filename service.yaml
+$ oc apply -f <filename>
 ----
 
 . For each set of ping events that you want to request, create a ping source in the same namespace as the event consumer.
 
-.. Copy the example YAML into a file named `ping-source.yaml`:
+.. Create a YAML file for the ping source:
 +
 [source,yaml]
 ----
@@ -63,14 +84,14 @@ spec:
 +
 [source,terminal]
 ----
-$ oc apply --filename ping-source.yaml
+$ oc apply -f <filename>
 ----
 
 . Check that the controller is mapped correctly by entering the following command:
 +
 [source,terminal]
 ----
-$ oc get pingsource.sources.knative.dev test-ping-source -oyaml
+$ oc get pingsource.sources.knative.dev <ping_source_name> -oyaml
 ----
 +
 .Example output
@@ -140,12 +161,13 @@ Data,
 ----
 
 .Deleting the ping source
+// move to separate procedure; out of scope for this PR
 
 * Delete the ping source:
 +
 [source,terminal]
 ----
-$ oc delete -f <ping_source_yaml_filename>
+$ oc delete -f <filename>
 ----
 +
 .Example command
diff --git a/modules/serverless-sinkbinding-kn.adoc b/modules/serverless-sinkbinding-kn.adoc
@@ -6,13 +6,14 @@
 [id="serverless-sinkbinding-kn_{context}"]
 = Creating a sink binding by using the Knative CLI
 
-This guide describes the steps required to create a sink binding instance using `kn` commands.
+You can use the `kn source binding create` command to create a sink binding by using the `kn` CLI. Using the `kn` CLI to create event sources provides a more streamlined and intuitive user interface than modifying YAML files directly.
 
 .Prerequisites
 
 * The {ServerlessOperatorName}, Knative Serving and Knative Eventing are installed on the cluster.
-* You have installed the `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}.
+* Install the Knative (`kn`) CLI.
+* Install the OpenShift (`oc`) CLI.
 
 [NOTE]
 ====
@@ -37,10 +38,11 @@ $ kn service create event-display --image quay.io/openshift-knative/knative-even
 $ kn source binding create bind-heartbeat --subject Job:batch/v1:app=heartbeat-cron --sink ksvc:event-display
 ----
 
-. Create a `CronJob` custom resource (CR).
+. Create a `CronJob` object.
 
-.. Create a file named `heartbeats-cronjob.yaml` and copy the following sample code into it:
+.. Create a cron job YAML file:
 +
+.Example cron job YAML file
 [source,yaml]
 ----
 apiVersion: batch/v1
@@ -94,11 +96,11 @@ For example, to add this label to a `CronJob` CR, add the following lines to the
 
 ====
 +
-.. After you have created the `heartbeats-cronjob.yaml` file, apply it by entering:
+.. Create the cron job:
 +
 [source,terminal]
 ----
-$ oc apply -f heartbeats-cronjob.yaml
+$ oc apply -f <filename>
 ----
 
 . Check that the controller is mapped correctly by entering the following command and inspecting the output:
diff --git a/modules/serverless-sinkbinding-odc.adoc b/modules/serverless-sinkbinding-odc.adoc
@@ -6,7 +6,7 @@
 [id="serverless-sinkbinding-odc_{context}"]
 = Creating a sink binding by using the web console
 
-You can create and verify a basic sink binding from the {product-title} web console.
+After Knative Eventing is installed on your cluster, you can create a sink binding by using the web console. Using the {product-title} web console provides a streamlined and intuitive user interface to create an event source.
 
 .Prerequisites
 
diff --git a/modules/serverless-sinkbinding-reference.adoc b/modules/serverless-sinkbinding-reference.adoc
@@ -5,8 +5,9 @@
 :_content-type: REFERENCE
 [id="serverless-sinkbinding-reference_{context}"]
 = Sink binding reference
+// this section probably needs a rewrite / restructure; feels like multiple modules maybe for a larger ref doc. Out of scope for this PR.
 
-This topic provides reference information about the configurable parameters for `SinkBinding` objects.
+You can use a `PodSpecable` object as an event source by creating a sink binding. You can configure multiple parameters when creating a `SinkBinding` object.
 
 `SinkBinding` objects support the following parameters:
 
@@ -49,7 +50,7 @@ This topic provides reference information about the configurable parameters for
 [id="serverless-sinkbinding-reference-subject-parameters_{context}"]
 == Subject parameter
 
-The `Subject` parameter references the resources for which the runtime contract is augmented by binding implementations.
+The `Subject` parameter references the resources for which the runtime contract is augmented by binding implementations. You can configure multiple fields for a `Subject` definition.
 
 The `Subject` definition supports the following fields:
 
@@ -101,8 +102,7 @@ The `Subject` definition supports the following fields:
 
 |===
 
-[id="serverless-sinkbinding-reference-subject-parameter-examples_{context}"]
-=== Subject parameter examples
+.Subject parameter examples
 
 Given the following YAML, the `Deployment` object named `mysubject` in the `default` namespace is selected:
 
@@ -166,7 +166,7 @@ spec:
 [id="serverless-sinkbinding-reference-cloudevent-overrides_{context}"]
 == CloudEvent overrides
 
-A `ceOverrides` definition provides overrides that control the CloudEvent's output format and modifications sent to the sink
+A `ceOverrides` definition provides overrides that control the CloudEvent's output format and modifications sent to the sink. You can configure multiple fields for the `ceOverrides` definition.
 
 A `ceOverrides` definition supports the following fields:
 
diff --git a/modules/serverless-sinkbinding-yaml.adoc b/modules/serverless-sinkbinding-yaml.adoc
diff --git a/serverless/develop/serverless-custom-event-sources.adoc b/serverless/develop/serverless-custom-event-sources.adoc
diff --git a/serverless/develop/serverless-pingsource.adoc b/serverless/develop/serverless-pingsource.adoc
