SRVKE-695: Updated event source descriptions

Author: abrennan89

_topic_map.yml

@@ -3083,7 +3083,7 @@ Topics:
 - Name: Event sources
   Dir: event_sources
   Topics:
-  - Name: Getting started with event sources
+  - Name: Understanding event sources
     File: knative-event-sources
   - Name: Listing event sources and event source types
     File: serverless-listing-event-sources

modules/serverless-functions-func-yaml-fields.adoc

@@ -134,4 +134,4 @@ The `runtime` field specifies the language runtime for your function, for exampl
 
 == template
 
-The `template` field specifies the type of the invocation event that triggers your function. You can set it to `http` for triggering with plain HTTP requests or to `events` for triggering with CloudEvents.
+The `template` field specifies the type of the invocation event that triggers your function. You can set it to `http` for triggering with plain HTTP requests or to `events` for triggering with cloud events.

modules/serverless-go-function-return-values.adoc

@@ -22,7 +22,7 @@ func Handle(ctx context.Context, res http.ResponseWriter, req *http.Request) {
 }
 ----
 
-Functions triggered by a CloudEvent might return nothing, `error`, or `CloudEvent` in order to push events into the Knative Eventing system. In this case, you must set a unique `ID`, proper `Source`, and a `Type` for the CloudEvent. The data can be populated from a defined structure, or from a `map`.
+Functions triggered by a cloud event might return nothing, `error`, or `CloudEvent` in order to push events into the Knative Eventing system. In this case, you must set a unique `ID`, proper `Source`, and a `Type` for the cloud event. The data can be populated from a defined structure, or from a `map`.
 
 .Example CloudEvent response
 [source,go]

modules/serverless-invoking-go-functions-cloudevent.adoc

@@ -1,11 +1,7 @@
-// Module included in the following assemblies
-//
-// * /serverless/functions/serverless-developing-go-functions.adoc
-
 [id="serverless-invoking-go-functions-cloudevent_{context}"]
-= Functions triggered by a CloudEvent
+= Functions triggered by a cloud event
 
-When an incoming CloudEvent is received, the event is invoked by the link:https://cloudevents.github.io/sdk-go/[CloudEvents Golang SDK] and the `Event` type as a parameter.
+When an incoming cloud event is received, the event is invoked by the link:https://cloudevents.github.io/sdk-go/[CloudEvents Golang SDK] and the `Event` type as a parameter.
 
 You can leverage the Golang link:https://golang.org/pkg/context/[Context] as an optional parameter in the function contract, as shown in the list of supported function signatures:
 
@@ -29,7 +25,7 @@ Handle(context.Context, cloudevents.Event) (*cloudevents.Event, error)
 [id="serverless-invoking-go-functions-cloudevent-example_{context}"]
 == CloudEvent trigger example
 
-A CloudEvent is received which contains a JSON string in the data property:
+A cloud event is received which contains a JSON string in the data property:
 
 [source,json]
 ----
@@ -39,7 +35,7 @@ A CloudEvent is received which contains a JSON string in the data property:
 }
 ----
 
-To access this data, a structure must be defined which maps properties in the CloudEvent data, and retrieves the data from the incoming event. The following example uses the `Purchase` structure:
+To access this data, a structure must be defined which maps properties in the cloud event data, and retrieves the data from the incoming event. The following example uses the `Purchase` structure:
 
 [source,go]
 ----
@@ -58,7 +54,7 @@ func Handle(ctx context.Context, event cloudevents.Event) (err error) {
 }
 ----
 
-Alternatively, a Golang `encoding/json` package could be used to access the CloudEvent directly as JSON in the form of a bytes array:
+Alternatively, a Golang `encoding/json` package could be used to access the cloud event directly as JSON in the form of a bytes array:
 
 [source,go]
 ----

modules/serverless-invoking-go-functions-http.adoc

@@ -1,7 +1,3 @@
-// Module included in the following assemblies
-//
-// * /serverless/functions/serverless-developing-go-functions.adoc
-
 [id="serverless-invoking-go-functions-http_{context}"]
 = Functions triggered by an HTTP request
 

modules/serverless-invoking-python-functions.adoc

@@ -1,14 +1,10 @@
-// Module included in the following assemblies
-//
-// * /serverless/functions/serverless-developing-python-functions.adoc
-
 [id="serverless-invoking-python-functions_{context}"]
 = About invoking Python functions
 
 Python functions can be invoked with a simple HTTP request. When an incoming request is received, functions are invoked with a `context` object as the first parameter. The `context` object is a Python class with two attributes:
 
 * The `request` attribute is always present, and contains the Flask `request` object.
-* The second attribute, `cloud_event`, is populated if the incoming request is a `CloudEvent`.
+* The second attribute, `cloud_event`, is populated if the incoming request is a `CloudEvent` object.
 
 Developers can access any `CloudEvent` data from the context object.
 

modules/serverless-invoking-quarkus-functions.adoc

@@ -5,7 +5,7 @@
 [id="serverless-invoking-quarkus-functions_{context}"]
 = About invoking Quarkus functions
 
-You can create a Quarkus project that responds to CloudEvents, or one that responds to simple HTTP requests. CloudEvents in Knative are transported over HTTP as a POST request, so either function type can listen and respond to incoming HTTP requests.
+You can create a Quarkus project that responds to cloud events, or one that responds to simple HTTP requests. Cloud events in Knative are transported over HTTP as a POST request, so either function type can listen and respond to incoming HTTP requests.
 
 When an incoming request is received, Quarkus functions are invoked with an instance of a permitted type.
 

serverless/admin_guide/serverless-cluster-admin-eventing.adoc

@@ -11,7 +11,7 @@ You can create Knative Eventing components with {ServerlessProductName} in the *
 // Event sources
 include::modules/serverless-creating-event-source-admin-web-console.adoc[leveloffset=+1]
 
-See xref:../../serverless/event_sources/knative-event-sources.adoc#knative-event-sources[Getting started with event sources] for more information on which event source types are supported and can be created using by {ServerlessProductName}.
+See xref:../../serverless/event_sources/knative-event-sources.adoc#knative-event-sources[Understanding event sources] for more information on which event source types are supported and can be created using by {ServerlessProductName}.
 
 // Brokers
 include::modules/serverless-creating-broker-admin-web-console.adoc[leveloffset=+1]

serverless/event_sources/knative-event-sources.adoc

@@ -1,25 +1,23 @@
 include::modules/serverless-document-attributes.adoc[]
 [id="knative-event-sources"]
-= Getting started with event sources
+= Understanding event sources
 include::modules/common-attributes.adoc[]
 :context: knative-event-sources
 
 toc::[]
 
-An _event source_ is an object that links an event producer with an event _sink_, or consumer. A sink can be a Knative service, channel, or broker that receives events from an event source.
+A Knative _event source_ can be any Kubernetes object that generates or imports cloud events, and relays those events to another endpoint, known as a xref:../../serverless/knative_eventing/serverless-event-sinks.adoc#serverless-event-sinks[_sink_]. Sourcing events is critical to developing a distributed system that reacts to events.
+
+You can create and manage Knative event sources by using the *Developer* perspective in the {product-title} web console, the `kn` CLI, or by applying YAML files.
 
 Currently, {ServerlessProductName} supports the following event source types:
 
-API server source:: Connects a sink to the Kubernetes API server.
-Ping source:: Periodically sends ping events with a constant payload. It can be used as a timer.
-Sink binding:: Connects core Kubernetes resource objects, such as `Deployment`, `Job`, or `StatefulSet` objects, with a sink.
-Container source:: Creates a custom event source by using an image.
-Knative Kafka source:: Connects a Kafka cluster to a sink as an event source.
+xref:../../serverless/event_sources/serverless-apiserversource.adoc#serverless-apiserversource[API server source]:: Brings Kubernetes API server events into Knative. The API server source fires a new event each time a Kubernetes resource is created, updated or deleted.
+
+xref:../../serverless/event_sources/serverless-pingsource.adoc#serverless-pingsource[Ping source]:: Produces events with a fixed payload on a specified cron schedule.
+
+xref:../../serverless/event_sources/serverless-sinkbinding.adoc#serverless-sinkbinding[Sink binding]:: Connects core Kubernetes resource objects, such as `Deployment`, `Job`, or `StatefulSet` objects, with a sink.
 
-You can create and manage Knative event sources using the *Developer* perspective in the {product-title} web console, the `kn` CLI, or by applying YAML files.
+xref:../../serverless/event_sources/serverless-containersource.adoc#serverless-containersource[Container source]:: Starts a container image that generates cloud events and sends them to a sink. Container sources can also be used to support your own custom event sources in Knative.
 
-* Create an xref:../../serverless/event_sources/serverless-apiserversource.adoc#serverless-apiserversource[API server source].
-* Create an xref:../../serverless/event_sources/serverless-pingsource.adoc#serverless-pingsource[ping source].
-* Create a xref:../../serverless/event_sources/serverless-sinkbinding.adoc#serverless-sinkbinding[sink binding].
-* Create a xref:../../serverless/event_sources/serverless-containersource.adoc#serverless-containersource[container source].
-* Create a xref:../../serverless/event_sources/serverless-kafka-source.adoc#serverless-kafka-source[Kafka source].
+xref:../../serverless/event_sources/serverless-kafka-source.adoc#serverless-kafka-source[Kafka source]:: Connects a Kafka cluster to a sink as an event source.

serverless/event_sources/serverless-kafka-source.adoc

@@ -24,6 +24,6 @@ include::modules/serverless-kafka-source-yaml.adoc[leveloffset=+1]
 [id="additional-resources_serverless-kafka-source"]
 == Additional resources
 
-* See xref:../../serverless/event_sources/knative-event-sources.adoc#knative-event-sources[Getting started with event sources].
+* See xref:../../serverless/event_sources/knative-event-sources.adoc#knative-event-sources[Understanding event sources].
 * See xref:../../serverless/knative_eventing/serverless-kafka.adoc#serverless-kafka[Knative Kafka].
 * See the link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.6/html/amq_streams_on_openshift_overview/kafka-concepts_str#kafka-concepts-key_str[Red Hat AMQ Streams] documentation for more information about Kafka concepts.