Extend event mesh topic (#5484)

* Extend event mesh topic

* Accept psschwei edits and link corrections.

Co-authored-by: Paul Schweigert <paul@paulschweigert.com>

* Fix links where I guessed wrong at URL scheme

Co-authored-by: Paul Schweigert <paul@paulschweigert.com>

* Fix typo

Co-authored-by: Matthias Wessendorf <mwessend@redhat.com>

---------

Co-authored-by: Paul Schweigert <paul@paulschweigert.com>
Co-authored-by: Matthias Wessendorf <mwessend@redhat.com>

docs/eventing/event-mesh.md

@@ -1,17 +1,19 @@
 # Event Mesh
 
-An Event Mesh is a dynamic infrastructure that is designed to smoothly transport events from producers to consumers via a network of interconnected _event brokers_ across any environment, and even between clouds in a seamless and loosely coupled way. In an Event Mesh both, producing and consuming application, can leverage their platform native event APIs. For instance a Python or Golang application can produce an event, using their native APIs, while a consuming application written in Java or Node.js can subscribe to it with their own native APIs as well.
+An Event Mesh is dynamic infrastructure which is designed to simplify distributing events from senders to recipients.  Similar to traditional message-channel architectures like Apache Kafka or RabbitMQ, an Event Mesh provides asynchronous (store-and-forward) delivery of messages which allows decoupling senders and recipients in time.  Unlike traditional message-channel based integration patterns, Event Meshes also simplify the routing concerns of senders and recipients by decoupling them from the underlying event transport infrastructure (which may be a federated set of solutions like Kafka, RabbitMQ, or cloud provider infrastructure).  The mesh transports events from producers to consumers via a network of interconnected _event brokers_ across any environment, and even between clouds in a seamless and loosely coupled way.
+
+In an Event Mesh, both producing and consuming applications do not need to implement event routing or subscription management.  Event producers can publish all events to the mesh, which can route events to interested subscribers without needing the application to subdivide events to channels.  Event consumers can use mesh configuration to receive events of interest using fine-grained filter expressions rather than needing to implement multiple subscriptions and application-level event filtering to select the events of interest.  Event serialization and de-serialization can be handled by language-native libraries without needing to implement heavier-weight routing and filtering.
 
 ## Knative Event Mesh
 
-The above mentioned _event brokers_ are directly mapping to a key API in Knative Eventing: The `Broker` API offers a discoverable endpoint for event ingress and the `Trigger` API completes the offering with its event delivery capabilities. With these APIs Knative Eventing offers an Event Mesh as defined above:
+The above mentioned _event brokers_ map directly to a core API in Knative Eventing: the [`Broker` API](../brokers) offers a discoverable endpoint for event ingress and the [`Trigger` API](../triggers) completes the offering with its event filtering and delivery capabilities.  With these APIs Knative Eventing offers an Event Mesh as defined above:
 
 ![Raw Trace](images/mesh.png)
 
-As visible in the above diagram, the Event Mesh is defined with the `Broker` and `Trigger` APIs for the ingress and the egress of events. Knative Eventing complements the Event Mesh with its Duck type APIs, offering a pool of connector for sending events to the `Broker` and routing events to subscribers using the `Trigger`:
+As visible in the above diagram, the Event Mesh is defined with the `Broker` and `Trigger` APIs for the ingress and the egress of events.  Knative Eventing enables multiple resources to participate in the Event Mesh with a partial schema pattern called "duck typing".  Duck typing allows multiple resource types to advertise common capabilities, such as "can receive events at a URL" or "can deliver events to a destination".  Knative Eventing uses these capabilities to offer [a pool of interoperable sources](../sources) for sending events to the `Broker` and [as destinations for `Trigger`-routed events](../triggers).  The Knative Eventing APIs contain three categories of APIs:
 
-* **Events Ingress**: Support for a connectors API: Source duck type & Callable/Addressable Duck type. Even without any sources installed.
-* **Event routing**: Broker + Triggers
-* **Event egress** : Sinks API (i.e Callable)
+* **Events Ingress**: Support for connecting event senders: Source duck type and [SinkBinding](./custom-event-source/sinkbinding) to support easily configuring applications to deliver events to a `Broker`.  Applications can submit events and use Eventing even without any sources installed.
+* **Event routing**: `Broker` and `Trigger` objects support defining the mesh and event routing.  Note that `Broker` matches the definition of an Addressable event destination, so it is possible to relay events from a Broker in one cluster to a Broker in another cluster.  Similarly, `Trigger` uses the same Deliverable duck type as many sources, so it is easy to substitute an event mesh for direct delivery of events.
+* **Event egress** : The Deliverable contract supports specifying either a bare URL or referencing a Kubernetes object which implements the Addressable interface (has a `status.address.url`) as a destination.  All event destinations ("sinks") must implement the CloudEvents delivery specification, but do not necessarily need to implement any Kubernetes behavior -- a bare VM referenced by URL is an acceptable event egress.
 
-It is important to note that `Source` and `Sink` are not directly part of the Event Mesh. However they are complementary, and benefit from the good Ducktype APIs (`Callable`/`Addressable`) for a smooth integration or connection with the "Event Mesh".
+It is important to note that event sources and sinks are supporting components of the eventing ecosystem but are not directly part of the Event Mesh.  While not part of the Event Mesh, these ecosystem components complement the mesh and benefit from the duck type APIs (`Callable`/`Addressable`) for a smooth integration or connection with the "Event Mesh".

docs/eventing/images/mesh.drawio

@@ -0,0 +1 @@
+<mxfile modified="2023-03-16T17:17:50.361Z" host="app.diagrams.net" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36" etag="ifytYFs2t7y4vGz_wMX6" version="13.6.2" type="device"><diagram id="f106602c-feb2-e66a-4537-3a34d633f6aa" name="Page-1">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</diagram></mxfile>