knative · knative-prow · Jul 29, 2022 · Jul 29, 2022 · Jul 29, 2022 · Jul 29, 2022
diff --git a/config/nav.yml b/config/nav.yml
@@ -5,6 +5,12 @@ nav:
     # Home page
 ###############################################################################
     - Home: index.md
+###############################################################################
+    # Concepts
+###############################################################################
+    - Concepts:
+      - Overview: concepts/README.md
+      - Duck types: concepts/duck-typing.md
 ###############################################################################
     # Getting started
 ###############################################################################
@@ -242,9 +248,8 @@ nav:
       - Eventing code samples: samples/eventing.md
     # Reference docs
     - Reference:
-      - Concepts:
-        - Duck types: reference/concepts/duck-typing.md
       - Security: reference/security/README.md
+      - Release notes: reference/relnotes/README.md
     - Contributing:
       - Welcome to the Knative community: contributing/README.md
       - Contribute to Knative: contributing/contributing.md

diff --git a/config/redirects.yml b/config/redirects.yml
@@ -1,6 +1,7 @@
 plugins:
   redirects:
     redirect_maps:
+      reference/concepts/duck-typing.md: concepts/duck-typing.md
       reference/client/README.md: client/README.md
       reference/api/eventing-api.md: eventing/reference/eventing-api.md
       reference/api/serving-api.md: serving/reference/serving-api.md
@@ -66,7 +67,7 @@ plugins:
       community/meetup.md: contributing/contributing.md
       community/samples.md: https://github.com/knative/docs/tree/main/code-samples/community
       concepts/overview.md: index.md
-      developer/concepts/duck-typing.md: reference/concepts/duck-typing.md
+      developer/concepts/duck-typing.md: concepts/duck-typing.md
       developer/eventing/event-delivery.md: eventing/event-delivery.md
       developer/eventing/sinks/README.md: eventing/sinks/README.md
       developer/eventing/sinks/kafka-sink.md: eventing/sinks/kafka-sink.md

diff --git a/docs/concepts/README.md b/docs/concepts/README.md
@@ -0,0 +1,15 @@
+# Concepts
+
+The documentation in this section explains commonly referenced Knative concepts and abstractions, and helps to provide you with a better understanding of how Knative works.
+
+## What is Knative?
+
+Knative is a platform-agnostic solution for running [serverless](https://en.wikipedia.org/wiki/Serverless_computing){target=_blank} deployments.
+
+## Knative Serving
+
+--8<-- "about-serving.md"
+
+## Knative Eventing
+
+--8<-- "about-eventing.md"
diff --git a/docs/reference/concepts/duck-typing.md → docs/concepts/duck-typing.md b/docs/reference/concepts/duck-typing.md → docs/concepts/duck-typing.md
diff --git a/docs/eventing/README.md b/docs/eventing/README.md
@@ -1,25 +1,19 @@
 # Knative Eventing
 
-Knative Eventing is a collection of APIs that enable you to use an [event-driven architecture](https://en.wikipedia.org/wiki/Event-driven_architecture) with your applications.
+--8<-- "about-eventing.md"
 
-You can use these APIs to create components that route events from event producers to event consumers, or _sinks_, that receive events. Sinks can also be configured to respond to HTTP requests by sending a response event.
-
-Knative Eventing uses standard HTTP POST requests to send and receive events between event producers and sinks. These events conform to the [CloudEvents specifications](https://cloudevents.io/), which enables creating, parsing, sending, and receiving events in any programming language.
-
-In a Knative Eventing deployment, event [Sources](../eventing/sources/README.md) are the primary event producers. Examples of [sinks](../eventing/sinks/README.md) include [Brokers](../eventing/broker/README.md), [Channels](../eventing/channels/README.md), and [Services](../serving/services/README.md).
+In a Knative Eventing deployment, event [Sources](../eventing/sources/README.md){target=_blank} are the primary event producers. Examples of [sinks](../eventing/sinks/README.md){target=_blank} include [Brokers](../eventing/broker/README.md){target=_blank}, [Channels](../eventing/channels/README.md){target=_blank}, and [Services](../serving/services/README.md){target=_blank}.
 
 ## Common use cases
 
-Knative Eventing components are loosely coupled, and can be developed and deployed independently of each other. Any producer can generate events before there are active event consumers that are listening for those events. Any event consumer can express interest in a class of events before there are producers that are creating those events.
-
 Examples of supported Knative Eventing use cases:
 
 - Publish an event without creating a consumer. You can send events to a broker as an HTTP POST, and use binding to decouple the destination configuration from your application that produces events.
 
 - Consume an event without creating a publisher. You can use a trigger to consume events from a broker based on event attributes. The application receives events as an HTTP POST.
 
 !!! tip
-    Multiple event producers and sinks can be used together to create more advanced [Knative Eventing flows](flows/README.md) to solve complex use cases.
+    Multiple event producers and sinks can be used together to create more advanced [Knative Eventing flows](flows/README.md){target=_blank} to solve complex use cases.
 
 ## Eventing examples
 

diff --git a/docs/eventing/sources/apiserversource/getting-started.md b/docs/eventing/sources/apiserversource/getting-started.md
@@ -224,7 +224,7 @@ command:
             - `<namespace>` is the name of the namespace that you created in step 1 earlier.
             - `<service-account>` is the name of the ServiceAccount that you created in step 2 earlier.
             - `<event-mode>` is either `Resource` or `Reference`. If set to `Resource`, the event payload contains the entire resource that the event is for. If set to `Reference`, the event payload only contains a reference to the resource that the event is for. The default is `Reference`.
-            - `<sink-kind>` is any supported [Addressable](../../../reference/concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`.
+            - `<sink-kind>` is any supported Addressable object that you want to use as a sink, for example, a `Service` or `Deployment`.
             - `<sink-name>` is the name of your sink.
 
             For more information about the fields you can configure for the ApiServerSource object, see [ApiServerSource reference](reference.md).

diff --git a/docs/eventing/sources/ping-source/README.md b/docs/eventing/sources/ping-source/README.md
@@ -150,7 +150,7 @@ during the verification step in this procedure.
                 - `<cron-schedule>` is a cron expression for the schedule for the PingSource to send events, for example, `*/1 * * * *` sends an event every minute.
                 - `<content-type>` is the media type of the data you want to send, for example, `application/json`.
                 - `<data>` is the data you want to send. This data must be represented as text, not binary. For example, a JSON object such as `{"message": "Hello world!"}`.
-                - `<sink-kind>` is any supported [Addressable](../../../reference/concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`.
+                - `<sink-kind>` is any supported Addressable object that you want to use as a sink, for example, a `Service` or `Deployment`.
                 - `<sink-name>` is the name of your sink, for example, `event-display`.
 
                 For more information about the fields you can configure for the PingSource object, see [PingSource reference](reference.md).
@@ -191,7 +191,7 @@ during the verification step in this procedure.
                 - `<cron-schedule>` is a cron expression for the schedule for the PingSource to send events, for example, `*/1 * * * *` sends an event every minute.
                 - `<content-type>` is the media type of the data you want to send, for example, `application/json`.
                 - `<base64-data>` is the base64 encoded binary data that you want to send, for example, `ZGF0YQ==`.
-                - `<sink-kind>` is any supported [Addressable](../../../reference/concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, a Kubernetes Service.
+                - `<sink-kind>` is any supported Addressable object that you want to use as a sink, for example, a Kubernetes Service.
                 - `<sink-name>` is the name of your sink, for example, `event-display`.
 
                 For more information about the fields you can configure for the PingSource object, see [PingSource reference](reference.md).

diff --git a/docs/serving/README.md b/docs/serving/README.md
@@ -1,6 +1,10 @@
 # Knative Serving
 
-Knative Serving provides components that enable:
+--8<-- "about-serving.md"
+
+## Common use cases
+
+Examples of supported Knative Serving use cases:
 
 - Rapid deployment of serverless containers.
 - Autoscaling, including scaling pods down to zero.
@@ -13,38 +17,6 @@ Knative Serving supports both HTTP and [HTTPS](using-a-tls-cert.md) networking p
 
 You can install Knative Serving via the methods listed on the [installation page](../install/README.md).
 
-## Serving resources
-
-Knative Serving defines a set of objects as Kubernetes Custom Resource
-Definitions (CRDs). These objects are used to define and control how your
-serverless workload behaves on the cluster:
-
-- [Service](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#service):
-  The `service.serving.knative.dev` resource automatically manages the whole
-  lifecycle of your workload. It controls the creation of other objects to
-  ensure that your app has a route, a configuration, and a new revision for each
-  update of the service. Service can be defined to always route traffic to the
-  latest revision or to a pinned revision.
-- [Route](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#route):
-  The `route.serving.knative.dev` resource maps a network endpoint to one or
-  more revisions. You can manage the traffic in several ways, including
-  fractional traffic and named routes.
-- [Configuration](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#configuration):
-  The `configuration.serving.knative.dev` resource maintains the desired state
-  for your deployment. It provides a clean separation between code and
-  configuration and follows the Twelve-Factor App methodology. Modifying a
-  configuration creates a new revision.
-- [Revision](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#revision):
-  The `revision.serving.knative.dev` resource is a point-in-time snapshot of the
-  code and configuration for each modification made to the workload. Revisions
-  are immutable objects and can be retained for as long as useful. Knative
-  Serving Revisions can be automatically scaled up and down according to
-  incoming traffic. See
-  [Configuring the Autoscaler](autoscaling/README.md) for more
-  information.
-
-![Diagram that displays how the Serving resources coordinate with each other.](https://github.com/knative/serving/raw/main/docs/spec/images/object_model.png)
-
 ## Getting Started
 
 To get started with Serving, check out one of the [hello world](../samples/serving.md)
@@ -55,8 +27,6 @@ With the `Service` resource, a deployed service will automatically have a
 matching route and configuration created. Each time the `Service` is updated, a
 new revision is created.
 
-For more information on the resources and their interactions, see the [Resource Types Overview](https://github.com/knative/specs/blob/main/specs/serving/overview.md) in the Knative Serving repository.
-
 ## More samples and demos
 
 - [Knative Serving code samples](../samples/serving.md)

diff --git a/docs/snippets/about-eventing.md b/docs/snippets/about-eventing.md
@@ -0,0 +1,9 @@
+<!-- Snippet used in the following topics:
+- /docs/eventing/README.md
+- /docs/concepts/README.md
+-->
+Knative Eventing is a collection of APIs that enable you to use an [event-driven architecture](https://en.wikipedia.org/wiki/Event-driven_architecture){target=_blank} with your applications. You can use these APIs to create components that route events from event producers to event consumers, known as sinks, that receive events. Sinks can also be configured to respond to HTTP requests by sending a response event.
+
+Knative Eventing uses standard HTTP POST requests to send and receive events between event producers and sinks. These events conform to the [CloudEvents specifications](https://cloudevents.io/){target=_blank}, which enables creating, parsing, sending, and receiving events in any programming language.
+
+Knative Eventing components are loosely coupled, and can be developed and deployed independently of each other. Any producer can generate events before there are active event consumers that are listening for those events. Any event consumer can express interest in a class of events before there are producers that are creating those events.
diff --git a/docs/snippets/about-serving.md b/docs/snippets/about-serving.md
@@ -0,0 +1,38 @@
+<!-- Snippet used in the following topics:
+- /docs/serving/README.md
+- /docs/concepts/README.md
+-->
+Knative Serving defines a set of objects as Kubernetes Custom Resource
+Definitions (CRDs). These resources are used to define and control how your
+serverless workload behaves on the cluster.
+
+The primary Knative Serving resources are Services, Routes, Configurations, and Revisions:
+
+![Diagram that displays how the Serving resources coordinate with each other.](https://github.com/knative/serving/raw/main/docs/spec/images/object_model.png)
+
+- [Service](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#service){target=_blank}:
+  The `service.serving.knative.dev` resource automatically manages the whole
+  lifecycle of your workload. It controls the creation of other objects to
+  ensure that your app has a route, a configuration, and a new revision for each
+  update of the service. Service can be defined to always route traffic to the
+  latest revision or to a pinned revision.
+
+- [Route](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#route){target=_blank}:
+  The `route.serving.knative.dev` resource maps a network endpoint to one or
+  more revisions. You can manage the traffic in several ways, including
+  fractional traffic and named routes.
+
+- [Configuration](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#configuration){target=_blank}:
+  The `configuration.serving.knative.dev` resource maintains the desired state
+  for your deployment. It provides a clean separation between code and
+  configuration and follows the Twelve-Factor App methodology. Modifying a
+  configuration creates a new revision.
+
+- [Revision](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#revision){target=_blank}:
+  The `revision.serving.knative.dev` resource is a point-in-time snapshot of the
+  code and configuration for each modification made to the workload. Revisions
+  are immutable objects and can be retained for as long as useful. Knative
+  Serving Revisions can be automatically scaled up and down according to
+  incoming traffic.
+
+For more information on the resources and their interactions, see the [Resource Types Overview](https://github.com/knative/specs/blob/main/specs/serving/overview.md){target=_blank} in the `serving` Github repository.