Apply suggestions from code review

Co-authored-by: Lucie Milan <[email protected]>
Co-authored-by: lena-larionova <[email protected]>

app/_gateway_entities/route.md

@@ -11,7 +11,7 @@ related_resources:
     url: /gateway/entities/service/
   - text: Expressions router
     url: /gateway/routing/expressions/
-  - text: Upstreams entity
+  - text: Upstream entity
     url: /gateway/entities/upstream/
   - text: Proxying with {{site.base_gateway}}
     url: /gateway/traffic-control/proxy/
@@ -31,7 +31,7 @@ schema:
 
 ## What is a Route? 
 
-{{page.description}} [Gateway Services](/gateway/entities/service/) can store collections of objects like plugin configurations, and policies, and they can be associated with Routes. In {{site.base_gateway}}, Routes typically map to endpoints that are exposed through the {{site.base_gateway}} application. Routes determine how (and if) requests are sent to their Services after they reach {{site.base_gateway}}. Where a Service represents the backend API, a Route defines what is exposed to clients. 
+{{page.description}} [Gateway Services](/gateway/entities/service/) can store collections of objects like plugin configurations and policies, and they can be associated with Routes. In {{site.base_gateway}}, Routes typically map to endpoints that are exposed through the {{site.base_gateway}} application. Routes determine how (and if) requests are sent to their Services after they reach {{site.base_gateway}}. Where a Service represents the backend API, a Route defines what is exposed to clients. 
 
 Routes can also define rules that match requests to associated Services. Because of this, one Route can reference multiple endpoints. Once a Route is matched, {{site.base_gateway}} proxies the request to its associated Service. A basic Route should have a name, path or paths, and reference an existing Service.
 
@@ -83,7 +83,7 @@ For example, say you have an external application and an internal application th
 
 In this example, you can create two Routes to handle the two applications, say `/external` and `/internal`, and point both of them to `example_service`. 
 You can configure a policy to limit how often the `/external` Route is used. 
-When the external application tries to access the Service via {{site.base_gateway}} using `/external`, they're rate limited. 
+When the external application tries to access the Service via {{site.base_gateway}} using `/external`, it's rate limited. 
 But when the internal application accesses the Service using {{site.base_gateway}} using `/internal`, the internal application isn't limited.
 
 ## How routing works
@@ -94,7 +94,7 @@ But when the internal application accesses the Service using {{site.base_gateway
 
 When you configure a Route, you must define certain attributes that {{site.base_gateway}} will use to match incoming requests.
 
-{{site.base_gateway}} supports native proxying of HTTP/HTTPS, TCP/TLS, and GRPC/GRPCS protocols. Each of these protocols accept a different set of routing attributes:
+{{site.base_gateway}} supports native proxying of HTTP/HTTPS, TCP/TLS, and GRPC/GRPCS protocols. Each of these protocols accepts a different set of routing attributes:
 - `http`: `methods`, `hosts`, `headers`, `paths` (and `snis`, if `https`)
 - `tcp`: `sources`, `destinations` (and `snis`, if `tls`)
 - `grpc`: `hosts`, `headers`, `paths` (and `snis`, if `grpcs`)
@@ -115,9 +115,9 @@ The following sections describe specifics about the headers, paths, and SNI attr
 
 **Supported protocols:** `http`and `grpc`
 
-Routing a request based on its Host header is the most straightforward way to proxy traffic through Kong Gateway, especially since this is the intended usage of the HTTP Host header. `hosts` accepts multiple values, which must be comma-separated when specifying them via the Admin API, and is represented in a JSON payload. You can also use wildcards in hostnames. Wildcard hostnames must contain only one asterisk at the leftmost or rightmost label of the domain.
+Routing a request based on its Host header is the most straightforward way to proxy traffic through {{site.base_gateway}}, especially since this is the intended usage of the HTTP Host header. `hosts` accepts multiple values, which must be comma-separated when specifying them via the Admin API, and is represented in a JSON payload. You can also use wildcards in hostnames. Wildcard hostnames must contain only one asterisk at the leftmost or rightmost label of the domain.
 
-When proxying, Kong Gateway’s default behavior is to set the Upstream request’s Host header to the hostname specified in the Service’s `host`. The `preserve_host` field accepts a boolean flag instructing Kong Gateway not to do so.
+When proxying, {{site.base_gateway}}’s default behavior is to set the upstream request’s Host header to the hostname specified in the Service’s `host`. The `preserve_host` field accepts a boolean flag instructing {{site.base_gateway}} not to do so.
 
 | Example config | Example routing request matches |
 |---------------|--------------------------------|
@@ -133,9 +133,9 @@ When proxying, Kong Gateway’s default behavior is to set the Upstream request
 
 Another way for a Route to be matched is via request paths. To satisfy this routing condition, a client request’s normalized path must be prefixed with one of the values of the `paths` attribute.
 
-Kong Gateway detects that the request's normalized URL path is prefixed with one of the Routes’ `paths` values. By default, Kong Gateway would then proxy the request Upstream without changing the URL path.
+{{site.base_gateway}} detects that the request's normalized URL path is prefixed with one of the Routes’ `paths` values. By default, {{site.base_gateway}} would then proxy the request Upstream without changing the URL path.
 
-When proxying with path prefixes, the longest paths get evaluated first. This allow you to define two Routes with two paths: `/service` and `/service/resource`, and ensure that the former does not “shadow” the latter.
+When proxying with path prefixes, the longest paths get evaluated first. This allows you to define two Routes with two paths: `/service` and `/service/resource`, and ensure that the former doesn't “shadow” the latter.
 
 * **Regex in paths:** For a path to be considered a regular expression, it must be prefixed with a `~`. For example: `paths: ["~/foo/bar$"]`. 
 * **Evaluation order:** The router evaluates Routes using the `regex_priority` field of the Route where a Route is configured. Higher `regex_priority` values mean higher priority. If you have the following paths configured:
@@ -168,7 +168,7 @@ When proxying with path prefixes, the longest paths get evaluated first. This al
 * **Normalization behavior:** To prevent trivial Route match bypass, the incoming request URI from client
 is always normalized according to [RFC 3986](https://tools.ietf.org/html/rfc3986)
 before router matching occurs. Specifically, the following normalization techniques are
-used for incoming request URIs, which are selected because they generally do not change
+used for incoming request URIs, which are selected because they generally don't change
 semantics of the request URI:
   1. Percent-encoded triplets are converted to uppercase.  For example: `/foo%3a` becomes `/foo%3A`.
   2. Percent-encoded triplets of unreserved characters are decoded. For example: `/fo%6F` becomes `/foo`.
@@ -191,7 +191,7 @@ Routers with a large number of regexes can consume traffic intended for other ru
 
 You can use a [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) as a routing attribute. 
 
-Incoming requests with a matching hostname set in the TLS connection’s SNI extension would be Routed to this Route. As mentioned, SNI routing applies not only to TLS, but also to other protocols carried over TLS, such as HTTPS. If multiple SNIs are specified in the Route, any of them can match with the incoming request’s SNI (or relationship between the names).
+Incoming requests with a matching hostname set in the TLS connection’s SNI extension would be routed to this Route. As mentioned, SNI routing applies not only to TLS, but also to other protocols carried over TLS, such as HTTPS. If multiple SNIs are specified in the Route, any of them can match with the incoming request’s SNI (or relationship between the names).
 
 The SNI is indicated at TLS handshake time and can't be modified after the TLS connection has been established. This means keepalive connections that send multiple requests will have the same SNI hostnames while performing router match (regardless of the `host` header).
 
@@ -225,7 +225,7 @@ The routing method you should use depends on your {{site.base_gateway}} version:
 In `traditional_compat` mode, the priority of a Route is determined as
 follows, by the order of descending significance:
 
-1. **Priority points:** For the presence of each of a Route's `methods`, `host`, `headers`, and `snis`, a "priority point" is added. The number of "priority points" determines the overall order in which the Routes will be considered. Routes with a higher "priority point" values will be considered before those with lower values. This means that if one Route has `methods` defined, and second one has `methods` and `headers` defined, the second one will be considered before the first one.
+1. **Priority points:** For the presence of each of a Route's `methods`, `host`, `headers`, and `snis`, a "priority point" is added. The number of "priority points" determines the overall order in which the Routes will be considered. Routes with higher "priority point" values will be considered before those with lower values. This means that if one Route has `methods` defined, and second one has `methods` and `headers` defined, the second one will be considered before the first one.
 2. **Wildcard hosts:** Among Routes with the same "priority point" value, those that have any wildcard host specification will be considered after those that don't have any wildcard host (or no host) specified.
 3. **Header count:** The resulting groups are sorted so the Routes with a higher number of specified headers have higher priority than those with a lower number of headers.
 4. **Regular expressions and prefix paths:** Within the resulting groups of Routes with equal priority, the router sorts them as follows:

app/_gateway_entities/target.md

@@ -11,10 +11,10 @@ tools:
     - deck
     - terraform
 
-description: A target is an IP address/hostname with a port that identifies an instance of a backend service.
+description: A Target is an IP address/hostname with a port that identifies an instance of a backend service.
 
 related_resources:
-  - text: Upstreams entity
+  - text: Upstream entity
     url: /gateway/entities/upstream/
   - text: Routing in {{site.base_gateway}}
     url: /gateway/routing/
@@ -27,9 +27,9 @@ schema:
 
 ---
 
-## What is a target?
+## What is a Target?
 
-{{page.description}} Each [Upstream](/gateway/entities/upstream/) can have many Targets. Targets are used by Upstreams for [load balancing]<!--TODO link concept-->. For example, if you have an `example_upstream` upstream, you can point it to two different Targets: `httpbin.konghq.com` and `httpbun.com`. This is so that if one of the servers (like `httpbin.konghq.com`) is unavailable, it automatically detects the problem and routes all traffic to the working server (`httpbun.com`).
+{{page.description}} Each [Upstream](/gateway/entities/upstream/) can have many Targets. Targets are used by Upstreams for [load balancing]<!--TODO link concept-->. For example, if you have an `example_upstream` Upstream, you can point it to two different Targets: `httpbin.konghq.com` and `httpbun.com`. This is so that if one of the servers (like `httpbin.konghq.com`) is unavailable, it automatically detects the problem and routes all traffic to the working server (`httpbun.com`).
 
 The following diagram illustrates how Targets are used by Upstreams for load balancing:
 
@@ -68,8 +68,8 @@ flowchart LR
 {% entity_example %}
 type: target
 data:
-    upstream: 
-      description: example_upstream
-      id: 173a6cee-90d1-40a7-89cf-0329eca780a6
-    weight: 100
+   - target: httpbun.com:80
+     weight: 100
+   - target: httpbin.konghq.com:80
+     weight: 100
 {% endentity_example %}

app/_gateway_entities/upstream.md

@@ -16,18 +16,16 @@ tools:
 description: An upstream refers to the service applications sitting behind {{site.base_gateway}}, to which client requests are forwarded.
 
 related_resources:
-  - text: Gateway Services entity
+  - text: Gateway Service entity
     url: /gateway/entities/service/
-  - text: Routes entity
+  - text: Route entity
     url: /gateway/entities/route/
-  - text: Targets entity
+  - text: Target entity
     url: /gateway/entities/target/
   - text: Routing in {{site.base_gateway}}
     url: /gateway/routing/
   - text: Expressions router
     url: /gateway/routing/expressions/
-  - text: Upstreams
-    url: /gateway/entities/upstream/
   - text: Proxying with {{site.base_gateway}}
     url: /gateway/traffic-control/proxy/
 
@@ -38,20 +36,20 @@ schema:
 
 ## What is an Upstream?
 
-{{page.description}} In {{site.base_gateway}}, an Upstream represents a virtual hostname and can be used to [health check, circuit break]<!--TODO link concept-->, and [load balance]<!--TODO link concept--> incoming requests over multiple [Gateway Services](/gateway/entities/service/). In addition, the upstream entity has more advanced functionality algorithms like least-connections, consistent-hashing, and lowest-latency.
+{{page.description}} In {{site.base_gateway}}, an Upstream represents a virtual hostname and can be used to [health check, circuit break]<!--TODO link concept-->, and [load balance]<!--TODO link concept--> incoming requests over multiple [Gateway Services](/gateway/entities/service/). In addition, the Upstream entity has more advanced functionality algorithms like least-connections, consistent-hashing, and lowest-latency.
 
-If you don't need to load balance hostnames, we recommend using the `host` header on a [Route](/gateway/entities/route/) as the preferred method for routing a request and proxying traffic.
+If you don't need to load balance, we recommend using the `host` header on a [Route](/gateway/entities/route/) as the preferred method for routing a request and proxying traffic.
 
 ## Upstream and Service interaction
 
 You can configure a Service to point to an Upstream instead of a host. 
 For example, if you have a Service called `example_service` and an Upstream called `example_upstream`, you can point `example_service` to `example_upstream` instead of specifying a host. 
-The `example_upstream` Upstream can then point to two different [targets](/gateway/entities/target/): `httpbin.konghq.com` and `httpbun.com`. 
+The `example_upstream` Upstream can then point to two different [Targets](/gateway/entities/target/): `httpbin.konghq.com` and `httpbun.com`. 
 In a real environment, the Upstream points to the same Service running on multiple systems.
 
-This setup allows you to [load balance]<!--TODO link concept--> between upstream targets. 
+This setup allows you to load balance between upstream targets. 
 For example, if an application is deployed across two different servers or upstream targets, {{site.base_gateway}} needs to load balance across both servers. 
-This is so that if one of the servers (like `httpbin.konghq.com` in the previous example) is unavailable, it automatically detects the problem and routes all traffic to the working server (`httpbun.com`). 
+If one of the servers (like `httpbin.konghq.com` in the previous example) is unavailable, it automatically detects the problem and routes all traffic to the working server (`httpbun.com`). 
 
 The following diagram shows how Upstreams interact with other {{site.base_gateway}} entities:
 

app/gateway/routing/expressions-router-examples.md

@@ -39,7 +39,7 @@ http.path ^= "/foo/bar"
 
 ### Regex based path matching
 
-If you prefer to match a HTTP requests path against a regex, you can write the following route:
+If you prefer to match an HTTP request's path against a regex, you can write the following route:
 
 ```
 http.path ~ r#"/foo/bar/\d+"#
@@ -65,7 +65,7 @@ http.headers.x_foo ~ r#"bar\d"#
 ```
 
 If there are multiple header values for `X-Foo` and the client sends more than
-one `X-Foo` header with different value, the above example will ensure **each** instance of the
+one `X-Foo` header with different values, the above example will ensure **each** instance of the
 value will match the regex `r#"bar\d"#`. This is called "all" style matching, meaning each instance
 of the field value must pass the comparison for the predicate to return `true`. This is the default behavior.
 

app/gateway/routing/expressions-router-reference.md

@@ -140,7 +140,7 @@ The following table describes the available matching fields, as well as their as
 
 An operator defines the desired comparison action to be performed on the field against the provided constant value. The operator always displays in the middle of the predicate, between the field and constant value.
 
-Expressions language support a rich set of operators that can be performed on various data types.
+The expressions language supports a rich set of operators that can be performed on various data types.
 
 | Operator       | Name                  | Description                  |
 |----------------|-----------------------|--------------------------------------------------------------------------------------|
@@ -250,7 +250,7 @@ expression: http.path == "/hello" || http.path == "/world"
 Regular expressions (regexes) are powerful tool that can be used to match strings based on
 very complex criteria. Unfortunately, this has also made them more expensive to
 evaluate at runtime and hard to optimize. Therefore, there are some common
-scenarios where regex usages can be eliminated, resulting in significantly
+scenarios where regex usage can be eliminated, resulting in significantly
 better matching performance.
 
 When performing exact matches (non-prefix matching) of a request path, use the `==` operator

app/gateway/traffic-control/proxy.md

@@ -85,7 +85,7 @@ one.
 - `stream_listen`, which is similar to `proxy_listen` but for Layer 4 (TCP, TLS)
   generic proxy. This is turned off by default.
 
-Kong Gateway is a transparent proxy, and it defaults to forwarding the request to your upstream service untouched, with the exception of various headers such as `Connection`, `Date`, and others as required by the HTTP specifications.
+{{site.base_gateway}} is a transparent proxy, and it defaults to forwarding the request to your upstream service untouched, with the exception of various headers such as `Connection`, `Date`, and others as required by the HTTP specifications.
 
 ## Routing
 
@@ -173,7 +173,7 @@ subsequent plugins added to the route or service that implement a hook in
 the `header_filter` phase.
 
 Once the `header_filter` phase of all registered plugins has been executed, the
-following headers are added by {{site.base_gateway}} and the full set of headers be sent to
+following headers are added by {{site.base_gateway}} and the full set of headers is sent to
 the client:
 
 | Header                                      | Description |