Cleaning up sink docs (#3814)

* Cleaning up sink docs

* fix links and heading

docs/developer/eventing/sinks/README.md

@@ -1,4 +1,4 @@
-# Event sinks
+# About sinks
 
 When you create an event source, you can specify a _sink_ where events are sent to from the source. A sink is an Addressable resource that can receive incoming events from other resources. Knative Services, Channels, and Brokers are all examples of sinks.
 
@@ -25,6 +25,53 @@ Where;
 - `<trigger-name>` is the name of the Trigger being connected to the sink.
 - `<kafka-sink-name>` is the name of a KafkaSink object.
 
+## Sink as a parameter
+
+Sink is used as a reference to an object that resolves to a URI to use as the sink.
+
+A `sink` definition supports the following fields:
+
+| Field | Description | Required or optional |
+|-------|-------------|----------------------|
+| `ref` | This points to an Addressable. | Required if _not_ using `uri`  |
+| `ref.apiVersion` | API version of the referent. | Required if using `ref` |
+| [`ref.kind`][kubernetes-kinds] | Kind of the referent. | Required if using `ref` |
+| [`ref.namespace`][kubernetes-namespaces] | Namespace of the referent. If omitted this defaults to the object holding it. | Optional |
+| [`ref.name`][kubernetes-names] | Name of the referent. | Required if using `ref` |
+| `uri` | This can be an absolute URL with a non-empty scheme and non-empty host that points to the target or a relative URI. Relative URIs are resolved using the base URI retrieved from Ref. | Required if _not_ using `ref` |
+
+!!! note
+    At least one of `ref` or `uri` is required. If both are specified, `uri` is
+    resolved into the URL from the Addressable `ref` result.
+
+### Sink parameter example
+
+Given the following YAML, if `ref` resolves into
+`"http://mysink.default.svc.cluster.local"`, then `uri` is added to this
+resulting in `"http://mysink.default.svc.cluster.local/extra/path"`.
+
+<!-- TODO we should have a page to point to describing the ref+uri destinations and the rules we use to resolve those and reuse the page. -->
+
+```yaml
+apiVersion: sources.knative.dev/v1
+kind: SinkBinding
+metadata:
+  name: bind-heartbeat
+spec:
+  ...
+  sink:
+    ref:
+      apiVersion: v1
+      kind: Service
+      namespace: default
+      name: mysink
+    uri: /extra/path
+```
+
+!!! contract
+    This results in the `K_SINK` environment variable being set on the `subject`
+    as `"http://mysink.default.svc.cluster.local/extra/path"`.
+
 ## Using custom resources as sinks
 
 To use a Kubernetes custom resource (CR) as a sink for events, you must:
@@ -73,7 +120,7 @@ kn source binding create bind-heartbeat \
 The `svc` in `http://event-display.svc.cluster.local` determines that the sink is a Knative Service. Other default sink prefixes include Channel and Broker.
 
 !!! tip
-    You can configure which resources can be used with the `--sink` flag for `kn` CLI commands by [Customizing kn](../../../../client/configure-kn/#customizing-kn).
+    You can configure which resources can be used with the `--sink` flag for `kn` CLI commands by [Customizing kn](../../../../client/configure-kn/#example-configuration-file).
 
 ## Supported third-party sink types
 

docs/eventing/sources/sinkbinding/reference.md

@@ -2,13 +2,11 @@
 
 ![API version v1](https://img.shields.io/badge/API_Version-v1-red?style=flat-square)
 
-This topic provides reference information about the configurable fields for the
+This topic provides reference information about the configurable parameters for SinkBinding objects.
-SinkBinding object.
 
+## Supported parameters
 
-## SinkBinding
+A `SinkBinding` resource supports the following parameters:
-
-A `SinkBinding` definition supports the following fields:
 
 | Field | Description | Required or optional |
 |-------|-------------|----------------------|
@@ -16,59 +14,10 @@ A `SinkBinding` definition supports the following fields:
 | [`kind`][kubernetes-overview] | Identifies this resource object as a `SinkBinding` object. | Required |
 | [`metadata`][kubernetes-overview] | Specifies metadata that uniquely identifies the `SinkBinding` object. For example, a `name`. | Required |
 | [`spec`][kubernetes-overview] | Specifies the configuration information for this `SinkBinding` object. | Required |
-| [`spec.sink`](#sink-parameter) | A reference to an object that resolves to a URI to use as the sink. | Required |
+| [`spec.sink`](../../../../developer/eventing/sinks) | A reference to an object that resolves to a URI to use as the sink. | Required |
 | [`spec.subject`](#subject-parameter) | A reference to the resources for which the "runtime contract" is augmented by Binding implementations. | Required |
 | [`spec.ceOverrides`](#cloudevent-overrides) | Defines overrides to control the output format and modifications to the event sent to the sink. | Optional |
 
-
-### Sink parameter
-
-Sink is a reference to an object that resolves to a URI to use as the sink.
-
-A `sink` definition supports the following fields:
-
-| Field | Description | Required or optional |
-|-------|-------------|----------------------|
-| `ref` | This points to an Addressable. | Required if _not_ using `uri`  |
-| `ref.apiVersion` | API version of the referent. | Required if using `ref` |
-| [`ref.kind`][kubernetes-kinds] | Kind of the referent. | Required if using `ref` |
-| [`ref.namespace`][kubernetes-namespaces] | Namespace of the referent. If omitted this defaults to the object holding it. | Optional |
-| [`ref.name`][kubernetes-names] | Name of the referent. | Required if using `ref` |
-| `uri` | This can be an absolute URL with a non-empty scheme and non-empty host that points to the target or a relative URI. Relative URIs are resolved using the base URI retrieved from Ref. | Required if _not_ using `ref` |
-
-!!! note
-    At least one of `ref` or `uri` is required. If both are specified, `uri` is
-    resolved into the URL from the Addressable `ref` result.
-
-#### Example: Sink parameter
-
-Given the following YAML, if `ref` resolves into
-`"http://mysink.default.svc.cluster.local"`, then `uri` is added to this
-resulting in `"http://mysink.default.svc.cluster.local/extra/path"`.
-
-<!-- TODO we should have a page to point to describing the ref+uri destinations and the rules we use to resolve those and reuse the page. -->
-
-```yaml
-apiVersion: sources.knative.dev/v1
-kind: SinkBinding
-metadata:
-  name: bind-heartbeat
-spec:
-  ...
-  sink:
-    ref:
-      apiVersion: v1
-      kind: Service
-      namespace: default
-      name: mysink
-    uri: /extra/path
-```
-
-!!! contract
-    This results in the `K_SINK` environment variable being set on the `subject`
-    as `"http://mysink.default.svc.cluster.local/extra/path"`.
-
-
 ### Subject parameter
 
 The Subject parameter references the resources for which the "runtime contract"
@@ -89,7 +38,7 @@ A `subject` definition supports the following fields:
 | `selector.matchExpressions.values` | An array of string values. If `operator` is `In` or `NotIn`, the values array must be non-empty. If `operator` is `Exists` or `DoesNotExist`, the values array must be empty. This array is replaced during a strategic merge patch. | Required if using `matchExpressions` |
 | `selector.matchLabels` | A map of key-value pairs. Each key-value pair in the `matchLabels` map is equivalent to an element of `matchExpressions`, where the key field is `matchLabels.<key>`, the `operator` is `In`, and the `values` array contains only "matchLabels.<value>". The requirements are ANDed. | Use one of `matchExpressions` or `matchLabels` |
 
-#### Example: Subject parameter using name
+#### Subject parameter examples
 
 Given the following YAML, the `Deployment` named `mysubject` in the `default`
 namespace is selected:
@@ -108,8 +57,6 @@ spec:
   ...
 ```
 
-#### Example: Subject parameter using matchLabels
-
 Given the following YAML, any `Job` with the label `working=example` in the
 `default` namespace is selected:
 
@@ -129,8 +76,6 @@ spec:
   ...
 ```
 
-#### Example: Subject parameter using matchExpression
-
 Given the following YAML, any `Pod` with the label `working=example` OR
 `working=sample` in the ` default` namespace is selected:
 
@@ -154,7 +99,6 @@ spec:
   ...
 ```
 
-
 ### CloudEvent Overrides
 
 CloudEvent Overrides defines overrides to control the output format and
@@ -172,7 +116,7 @@ A `ceOverrides` definition supports the following fields:
     the extensions override configuration. For example, you can not modify the
     `type` attribute.
 
-#### Example: CloudEvent Overrides
+#### CloudEvent Overrides example
 
 ```yaml
 apiVersion: sources.knative.dev/v1