Fix second round of PR comments

Signed-off-by: Nick Young <[email protected]>

Author: youngnick

geps/gep-713.md

@@ -5,10 +5,12 @@
 
 ## TLDR
 
-This GEP aims to standardize terminology and process around using one Kubernetes
+This GEP aims to standardize terminology and processes around using one Kubernetes
 object modify the functions of one or more other objects.
 
-Generally, a Kubernetes object that that _augments_ the behavior of an object
+This GEP defines some terms, firstly: _Metaresource_.
+
+A Kubernetes object that that _augments_ the behavior of an object
 in a standard way is called a _Metaresource_ are a type of object. ReferenceGrant
 is an example of this general type of metaresource, but it is far from the only
 one.
@@ -19,8 +21,8 @@ A "Policy Attachment" is a specific type of _metaresource_ that can affect speci
 settings across either one object (this is "Direct Policy Attachment"), or objects
 in a hierarchy (this is "Hierarchical Policy Attachment").
 
-Individual policy APIs must
-- be their own CRDs (e.g. `TimeoutPolicy`, `RetryPolicy` etc),
+Individual policy APIs:
+- must be their own CRDs (e.g. `TimeoutPolicy`, `RetryPolicy` etc),
 - can be included in the Gateway API API group and installation or be defined by
   implementations
 - and must include a common `TargetRef` struct in their specification to identify how and where to
@@ -139,8 +141,9 @@ Importantly, this would apply to _every_ usage of that Service across any HTTPRo
 in that namespace, which could be useful for a Service that is reused in a lot of
 HTTPRoutes.
 
-With this two examples in mind, here are some guidelines for when to consider
+With these two examples in mind, here are some guidelines for when to consider
 using Direct Policy Attachment:
+
 * The number or scope of objects to be modified is limited or singular. Direct
   Policy Attachments should target one specific object (preferred), or a tightly-scoped
   set of objects (like all Services in a namespace).
@@ -160,7 +163,7 @@ using Direct Policy Attachment:
   consumer policies, but in general, Policy objects that modify the behavior of
   things outside their own namespace should be avoided unless it uses a handshake
   of some sort, where the things outside the namespace can opt–out of the behavior.
-  (Notably, this is the design that we used for ReferenceGrant).)
+  (Notably, this is the design that we used for ReferenceGrant).
 
 ### Hierarchical Policy Attachment: It's all about the defaults and overrides
 

site-src/references/policy-attachment.md

@@ -1,10 +1,14 @@
 # Metaresources and Policy Attachment
 
-Generally, a Kubernetes object that that _augments_ the behavior of an object
-in a standard way is called a _Metaresource_ are a type of object. ReferenceGrant
+The Gateway API defines a Kubernetes object that that _augments_ the behavior of an object
+in a standard way as a _Metaresource_. ReferenceGrant
 is an example of this general type of metaresource, but it is far from the only
 one.
 
+This document also defines a concept called _Policy Attachment_, which augments
+the behavior of an object to add additional settings that can't be described
+within the spec of that object.
+
 Why have this class of attachment? Well, while features like timeouts, retries,
 and custom health checks are present in most implementations, their details vary
 since there are no standards (RFCs) around them. This makes these features less
@@ -82,9 +86,10 @@ struct included in the Gateway API. Where possible, it is recommended to use
 that struct directly instead of duplicating the type.
 
 ### Policy Boilerplate
-The following structure MUST be used as for any Policy resource using this API
-pattern. Within the spec, policy resources may omit `Override` or `Default`
-fields, but at least one of them MUST be present.
+The following (or something like it) SHOULD be used as for any Policy resource using this API
+pattern. Within the spec, policy resources _may_ omit `Override` or `Default`
+fields for Direct Policy Attachment, but Hierarchical Policy Attachment must include
+one or both.
 
 ```go
 // ACMEServicePolicy provides a way to apply Service policy configuration with
@@ -133,7 +138,7 @@ type ACMEServicePolicyStatus struct {
 ```
 
 ### Hierarchy
-Each policy SHOULD include default and/or override values. Overrides enable admins to
+Each Hierarchical policy MUST include default and/or override values. Overrides enable admins to
 enforce policy from the top down. Defaults enable app owners to provide default
 values from the bottom up for each individual application.