SRVCOM-1728: Updating broker and trigger abstracts for Jupiter guidelines

modules/delete-kn-trigger.adoc

@@ -6,12 +6,12 @@
 [id="delete-kn-trigger_{context}"]
 = Deleting a trigger by using the Knative CLI
 
-You can use the `kn trigger delete` command to delete a trigger.
+Using the `kn` CLI to delete a trigger provides a streamlined and intuitive user interface. You can use the `kn trigger delete` command to delete a trigger.
 
 .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

modules/kn-trigger-describe.adoc

@@ -6,12 +6,12 @@
 [id="kn-trigger-describe_{context}"]
 = Describing a trigger by using the Knative CLI
 
-You can use the `kn trigger describe` command to print information about a trigger.
+Using the `kn` CLI to describe triggers provides a streamlined and intuitive user interface. You can use the `kn trigger describe` command to print information about existing triggers in your cluster 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 trigger.
 
 .Procedure

modules/kn-trigger-filtering.adoc

@@ -5,6 +5,9 @@
 :_content-type: REFERENCE
 [id="kn-trigger-filtering_{context}"]
 = Filtering events with triggers by using the Knative CLI
+// should be a procedure module but out of scope for this PR
+
+Using the `kn` CLI to filter events by using triggers provides a streamlined and intuitive user interface. You can use the `kn trigger create` command, along with the appropriate flags, to filter events by using triggers.
 
 In the following trigger example, only events with the attribute `type: dev.knative.samples.helloworld` are sent to the event sink:
 

modules/kn-trigger-list.adoc

@@ -6,12 +6,12 @@
 [id="kn-trigger-list_{context}"]
 = Listing triggers by using the Knative CLI
 
-The `kn trigger list` command prints a list of available triggers.
+Using the `kn` CLI to list triggers provides a streamlined and intuitive user interface. You can use the `kn trigger list` command to list existing triggers in your cluster.
 
 .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.
 
 .Procedure
 

modules/kn-trigger-update.adoc

@@ -6,12 +6,12 @@
 [id="kn-trigger-update_{context}"]
 = Updating a trigger by using the Knative CLI
 
-You can use the `kn trigger update` command with certain flags to update attributes for a trigger.
+Using the `kn` CLI to update triggers provides a streamlined and intuitive user interface. You can use the `kn trigger update` command with certain flags to update attributes for a trigger.
 
 .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

modules/serverless-broker-types.adoc

@@ -21,4 +21,7 @@ The channel-based broker implementation internally uses channels for event deliv
 [id="serverless-using-brokers-kafka"]
 == Kafka broker
 
+:FeatureName: Kafka broker
+include::snippets/technology-preview.adoc[leveloffset=+2]
+
 The Kafka broker is a broker implementation that uses Kafka internally to provide at-least once delivery guarantees. It supports multiple Kafka versions, and has a native integration with Kafka for storing and routing events.

modules/serverless-create-broker-kn.adoc

@@ -6,10 +6,12 @@
 [id="serverless-create-broker-kn_{context}"]
 = Creating a broker by using the Knative CLI
 
+Brokers can be used in combination with triggers to deliver events from an event source to an event sink. Using the `kn` CLI to create brokers provides a more streamlined and intuitive user interface over modifying YAML files directly. You can use the `kn broker create` command to create a broker 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
@@ -37,6 +39,7 @@ NAME      URL
 default   http://broker-ingress.knative-eventing.svc.cluster.local/test/default   45s   5 OK / 5     True
 ----
 
-. Optional: If you are using the {product-title} web console, you can navigate to the **Topology** view in the **Developer** perspective, and observe that the broker exists:
+. Optional: If you are using the {product-title} web console, you can navigate to the *Topology* view in the *Developer* perspective, and observe that the broker exists:
 +
 image::odc-view-broker.png[View the broker in the web console Topology view]
+// need to add separate docs for broker in ODC - out of scope for this PR

modules/serverless-create-kn-trigger.adoc

@@ -6,12 +6,12 @@
 [id="serverless-create-kn-trigger_{context}"]
 = Creating a trigger by using the Knative CLI
 
-You can create a trigger by using the `kn trigger create` command.
+Using the `kn` CLI to create triggers provides a more streamlined and intuitive user interface over modifying YAML files directly. You can use the `kn trigger create` command to create a trigger 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

modules/serverless-create-trigger-odc.adoc

@@ -6,7 +6,7 @@
 [id="serverless-create-trigger-odc_{context}"]
 = Creating a trigger by using the web console
 
-After you have created a broker, you can create a trigger by using the web console.
+Using the {product-title} web console provides a streamlined and intuitive user interface to create a trigger. After Knative Eventing is installed on your cluster and you have created a broker, you can create a trigger by using the web console.
 
 .Prerequisites
 
@@ -28,6 +28,7 @@ After you have created a broker, you can create a trigger by using the web conso
 * After the subscription has been created, you can view it in the *Topology* page, where it is represented as a line that connects the broker to the event sink.
 
 .Deleting a trigger
+// should be a separate module; out of scope for this PR
 
 . In the *Developer* perspective, navigate to the *Topology* page.
 . Click on the trigger that you want to delete.

modules/serverless-creating-broker-annotation.adoc

@@ -6,7 +6,7 @@
 [id="serverless-creating-broker-annotation_{context}"]
 = Creating a broker by annotating a trigger
 
-You can create a broker by adding the `eventing.knative.dev/injection: enabled` annotation to a `Trigger` object.
+Brokers can be used in combination with triggers to deliver events from an event source to an event sink. You can create a broker by adding the `eventing.knative.dev/injection: enabled` annotation to a `Trigger` object.
 
 [IMPORTANT]
 ====
@@ -17,7 +17,7 @@ If you delete the broker without having a cluster administrator remove this anno
 .Prerequisites
 
 * The {ServerlessOperatorName} and Knative Eventing 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
@@ -68,6 +68,7 @@ NAME      READY     REASON    URL
 default   True                http://broker-ingress.knative-eventing.svc.cluster.local/test/default   3m56s
 ----
 
-. Navigate to the *Topology* view in the web console, and observe that the broker exists:
+. Optional: If you are using the {product-title} web console, you can navigate to the *Topology* view in the *Developer* perspective, and observe that the broker exists:
 +
 image::odc-view-broker.png[View the broker in the web console Topology view]
+// need to add separate docs for broker in ODC - out of scope for this PR

modules/serverless-creating-broker-labeling.adoc

@@ -6,7 +6,7 @@
 [id="serverless-creating-broker-labeling_{context}"]
 = Creating a broker by labeling a namespace
 
-You can create the `default` broker automatically by labeling a namespace that you own or have write permissions for.
+Brokers can be used in combination with triggers to deliver events from an event source to an event sink. You can create the `default` broker automatically by labelling a namespace that you own or have write permissions for.
 
 [NOTE]
 ====
@@ -16,7 +16,7 @@ Brokers created using this method are not removed if you remove the label. You m
 .Prerequisites
 
 * The {ServerlessOperatorName} and Knative Eventing 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}.
 
 ifdef::openshift-dedicated[]
@@ -56,6 +56,7 @@ NAME      READY     REASON    URL
 default   True                http://broker-ingress.knative-eventing.svc.cluster.local/test/default   3m56s
 ----
 
-. Navigate to the *Topology* view in the web console, and observe that the broker exists:
+. Optional: If you are using the {product-title} web console, you can navigate to the *Topology* view in the *Developer* perspective, and observe that the broker exists:
 +
 image::odc-view-broker.png[View the broker in the web console Topology view]
+// need to add separate docs for broker in ODC - out of scope for this PR

modules/serverless-deleting-broker-injection.adoc

@@ -10,7 +10,7 @@ If you create a broker by injection and later want to delete it, you must delete
 
 .Prerequisites
 
-* Install the OpenShift CLI (`oc`).
+* Install the OpenShift (`oc`) CLI.
 
 .Procedure
 

modules/serverless-describe-broker-kn.adoc

@@ -6,10 +6,12 @@
 [id="serverless-describe-broker-kn_{context}"]
 = Describing an existing broker by using the Knative CLI
 
+Using the `kn` CLI to describe brokers provides a streamlined and intuitive user interface. You can use the `kn broker describe` command to print information about existing brokers in your cluster 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.
 
 .Procedure
 

modules/serverless-list-broker-kn.adoc

@@ -6,10 +6,12 @@
 [id="serverless-list-broker-kn_{context}"]
 = Listing existing brokers by using the Knative CLI
 
+Using the `kn` CLI to list brokers provides a streamlined and intuitive user interface. You can use the `kn broker list` command to list existing brokers in your cluster 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.
 
 .Procedure
 

serverless/develop/serverless-triggers.adoc

@@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Using triggers enables you to filter events from the broker for delivery to event sinks.
+include::snippets/serverless-brokers-intro.adoc[]
 
 // ODC
 include::modules/serverless-create-trigger-odc.adoc[leveloffset=+1]

serverless/develop/serverless-using-brokers.adoc

@@ -6,17 +6,10 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Brokers can be used in combination with xref:../../serverless/develop/serverless-triggers.adoc#serverless-triggers[triggers] to deliver events from an xref:../../serverless/discover/knative-event-sources.adoc#knative-event-sources[event source] to an event sink.
-
-image::serverless-event-broker-workflow.png[Broker event delivery overview]
-
-Events can be sent from an event source to a broker as an HTTP `POST` request. After events have entered the broker, they can be filtered by https://github.com/cloudevents/spec/blob/v1.0/spec.md#context-attributes[CloudEvent attributes] using triggers, and sent as an HTTP `POST` request to an event sink.
+include::snippets/serverless-brokers-intro.adoc[]
 
 include::modules/serverless-broker-types.adoc[leveloffset=+1]
 
-:FeatureName: Kafka broker
-include::snippets/technology-preview.adoc[leveloffset=+2]
-
 [id="serverless-using-brokers-creating-brokers"]
 == Creating a broker that uses default settings
 
@@ -38,5 +31,7 @@ include::modules/serverless-describe-broker-kn.adoc[leveloffset=+2]
 [id="additional-resources_serverless-using-brokers"]
 [role="_additional-resources"]
 == Additional resources
+* xref:../../serverless/develop/serverless-triggers.adoc#serverless-triggers[Triggers]
+xref:../../serverless/discover/knative-event-sources.adoc#knative-event-sources[Event sources]
 * xref:../../serverless/develop/serverless-event-delivery.adoc#serverless-event-delivery[Event delivery]
 * xref:../../serverless/develop/serverless-kafka-developer.adoc#serverless-kafka-developer-broker[Kafka broker]

snippets/serverless-brokers-intro.adoc

@@ -0,0 +1,10 @@
+// Text snippet included in the following modules:
+//
+// * /serverless/develop/serverless-using-brokers.adoc
+// * /serverless/develop/serverless-triggers.adoc
+
+:_content-type: SNIPPET
+
+Brokers can be used in combination with triggers to deliver events from an event source to an event sink. Events are sent from an event source to a broker as an HTTP `POST` request. After events have entered the broker, they can be filtered by https://github.com/cloudevents/spec/blob/v1.0/spec.md#context-attributes[CloudEvent attributes] using triggers, and sent as an HTTP `POST` request to an event sink.
+
+image::serverless-event-broker-workflow.png[Broker event delivery overview]