[WIP] Eventing Trigger Filtering docs

docs/eventing/README.md

@@ -46,10 +46,12 @@ easier to filter events.
 
 A Broker provides a bucket of events which can be selected by attribute. It
 receives events and forwards them to subscribers defined by one or more matching
-Triggers.
+Triggers. Each Trigger operates in the context of a single Broker. You can
+create as many Triggers as necessary.
 
 A Trigger describes a filter on event attributes which should be delivered to an
-Addressable. You can create as many Triggers as necessary.
+Addressable. See [Filtering][./filtering.md] for more information on specifying
+filters.
 
 ![Broker Trigger Diagram](./images/broker-trigger-overview.svg)
 
@@ -89,7 +91,7 @@ cluster) services, you must enable it also for them to work.
 
 ## Architecture
 
-The eventing infrastructure supports two forms of event delivery at the moment:
+The eventing infrastructure supports three forms of event delivery at the moment:
 
 1. Direct delivery from a source to a single Service (an Addressable endpoint,
    including a Knative Service or a core Kubernetes Service). In this case, the
@@ -103,6 +105,9 @@ The eventing infrastructure supports two forms of event delivery at the moment:
    In this case, the Channel implementation ensures that messages are delivered
    to the requested destinations and should buffer the events if the destination
    Service is unavailable.
+1. Selective delivery of events sent to a Broker via a Trigger specification
+   consisting of a filter and destination. This method provides the same
+   guarantees as the Channel and Subscription model.
 
 ![Control plane object model](./images/control-plane.png)
 

docs/eventing/filtering.md

@@ -0,0 +1,46 @@
+# Event Filters in Triggers
+
+Filters are used in Triggers to specify the set of events that are interesting
+to a subscriber. If you only want to receive some events, and you know which
+attributes identify the events you're interested in, use a filter in your
+Trigger to ensure the Trigger's subscriber will receive only events that match
+the filter.
+
+## Before you begin
+
+1.  Read about the [Broker and Trigger objects](./broker-trigger.md).
+1.  Be familiar with the
+    [CloudEvents spec](https://github.com/cloudevents/spec/blob/master/spec.md),
+    particularly the
+    [Context Attributes](https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes)
+    section.
+1.  Read the
+    [Common Expression Language introduction](https://github.com/google/cel-spec/blob/master/doc/intro.md),
+    and optionally the
+    [language definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md).
+
+## Filtering events
+
+Events can be filtered in one of two ways: by **attributes** and by **expression**. Only
+one of these filtering methods may be used per Trigger.
+
+### Filtering by attributes
+
+
+
+TODO "how to" info (the "task-oriented" step by step details for creating an
+event filter in a trigger) -> use a gerund in title (for example Filtering event
+attributes)
+
+## Filter examples
+
+### I want to receive events of a specific type
+
+TODO Example(s) (show them how and where they would/can create a filter in their
+trigger) i see lots in the proposal and it would be most consumable if we could
+organize these to some degree
+
+## Next steps
+
+TODO Link to what the next logical step would be (and include links to related
+info) to keep the user moving forward