docs: improve grammar and simplify HRQ examples

Was reading through the docs and these seemed the most verbose
- it seems to be a very recent feature as well, from 3aef487

- use same heading in both Quickstart and Concepts, including HRQ abbreviation
  - use abbreviation to shorten the HRQ docs themselves as well

- fix run-on sentences by adding punctuation
  - "by default, to use it" -> "by default. To use it"
- add missing commas
  - "Then,", "finally,", etc
- add Oxford commas
  - ", but", ", and", ", or", etc

- simplify several sentences, per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#use-simple-and-direct-language)
  - "won't be over the amount of resources that is configured in `HierarchicalResourceQuota`" -> "cannot surpass the HRQ"
    - "can't go over what is configured in the HRQ" -> "can't surpass the HRQ"
  - "And put the resources HRQ in" -> "An HRQ in"
    - "This will restrict whole" -> "restricts" (also uses present tense now, per style guide)
  - "the amount of resources that" -> "the resources"
  - "automatically creates" -> "creates"
- in a similar vein, remove or replace ambiguous language
  - "equally shared" -> "shared" -- they can be shared however, not necessarily "equally"
  - "which is very efficient" -> "" -- "efficient" could be interpreted in a performance sense and is unnecesary
  - "lower level", "level" -> "child" / "sub" -- use HNC's existing terminology instead of "lower level", which has multiple disambiguations
    - Similarly use HNC's existing terminology for:
      - "individual", "members" -> "namespace", "subnamespaces"
      - "above", "overall" -> "parent"
  - "wins" -> "applies" -- replace idiom, per [style guide](https://kubernetes.io/docs/contribute/style/style-guide/#avoid-jargon-and-idioms)

- clarify a few sentences with a single word
  - "within", "Instead", "still", "directly"

- consolidate the two paragraphs on command-line usage into one
  - looks like they were added at different times, in 564b4a9
  - they largely duplicated each other with slighlty different wording
  - creating an HRQ via a CR YAML is the definition of how CRs work, which are already used across HNC, so not necessary to re-explain
    - also remove the word "simply", per [style guide](https://kubernetes.io/docs/contribute/style/style-guide/#avoid-words-that-assume-a-specific-level-of-understanding)

There are potentially more changes that could be made according to the style guide, but I primarily limited changes to simplifications, clarifications, and grammar

Author: agilgur5

docs/user-guide/concepts.md

@@ -227,18 +227,18 @@ You can create a subnamespace from the command line via `kubectl hns create chil
 
 ***Hierarchical resource quotas are beta in HNC v1.1***
 
-***HRQs are not included by default, to use it install the hrq.yaml file in the [releases -> Assets](https://github.com/kubernetes-sigs/hierarchical-namespaces/releases)***
+***HRQs are not included by default. To use it, install the `hrq.yaml` file in [Releases -> Assets](https://github.com/kubernetes-sigs/hierarchical-namespaces/releases)***
 
 When you want to give some amount of resources to `team-a`, and want them to be able to
 flexibly use resources in any of their subnamespaces, you create a `HierarchicalResourceQuota`
-in namespace `team-a`. The sum of all resources from all the subnamespaces of the
-members won't be over the amount of resources that is configured in
-`HierarchicalResourceQuota` of namespace `team-a`. All of the resources of `team-a` are
-equally shared between the applications in their subnamespaces, which is very efficient.
+in namespace `team-a`. The sum of all resources from all subnamespaces of `team-a`
+cannot surpass the HRQ in namespace `team-a`. All of the resources of `team-a` are
+shared between applications in their subnamespaces.
 
-In addition, you can let an org or team's admin create their own hierarchical
-quotas without violating the overall HRQ for their org or team. For example,
+In addition, you can let an org or team's admin create sub-HRQs
+without violating the parent HRQ for their org or team. For example,
 if you start with the following structure:
+
 ```
 company-a
 ├── organization-a
@@ -251,42 +251,43 @@ company-a
 │   ...
 ...
 ```
-Instead of each team asking from the `cluster-admin` to modify their `ResourceQuota`,
-you can insert an additional "policy" namespace above each level to hold
-the policy objects (like hierarchical quota) that the sub-admin _cannot_
-change, while giving them permission to create their own quotas in the
-lower level namespaces, like this:
+
+Instead of each team asking a cluster admin to modify their `ResourceQuota`,
+you can insert an additional "policy" parent namespace to hold
+policy objects like HRQ. The sub-admin _cannot_ change the parent policies,
+but still has permission to create sub-HRQs in their subnamespaces, like this:
+
 ```
 company-a-policy
 └── company-a
 ```
-And put the resources HRQ in the `company-a-policy` namespace. This will restrict
-whole `company-a` to the amount of resources that they are paying for. Then `company-a`
-can do similar HRQ with their organizations:
+
+An HRQ in the `company-a-policy` namespace restricts
+`company-a` to the resources they are paying for. Then, `company-a`
+can create sub-HRQs for their internal organizations:
+
 ```
 company-a-policy (has HRQ)
 └── company-a
-    ├── org-a-policy (has HRQ)
+    ├── org-a-policy (has sub-HRQ)
     │   └── organization-a
-    ├── org-b-policy (has HRQ)
+    ├── org-b-policy (has sub-HRQ)
     │   └── organization-b
     ...
 ```
-Lower-level quotas cannot override more restrictive quotas from ancestor namespaces;
-the most restrictive quota always wins.
-This way each individual can fairly and securely distribute their resources across
-their members.
-
-You can create the HRQ `CustomResource` by simply applying a yaml file, and see usage via `kubectl hns hrq` or `kubectl get hrq`. See
-[quickstart example](quickstart.md#hrq) for reference.
 
+Child quotas cannot override more restrictive quotas from ancestor namespaces;
+the most restrictive quota always applies.
+This way, each namespace can fairly and securely distribute their resources across
+their subnamespaces.
 
-To implement hierarchical quotas, HNC automatically creates `ResourceQuota` objects in each
-affected namespace. This is a part of the internal implementation and shouldn't be modified or
-inspected. Use the `kubectl hns hrq` command to inspect hierarchical quotas,
-or look at the `HierarchicalResourceQuota` object in the ancestor namespaces.
+To implement hierarchical quotas, HNC creates `ResourceQuota` objects in each
+affected namespace. This is part of the internal implementation and shouldn't be modified or
+inspected directly. Instead, use `kubectl hns hrq` to inspect hierarchical quotas
+or, in ancestor namespaces, `kubectl get hrq`.
+See the [quickstart example](quickstart.md#hrq) for reference.
 
-Note: Decimal point values cannot be specified in HRQ (you can't do `cpu: 1.5` but you can do `cpu: "1.5"` or `cpu: 1500m`). See [#292](https://github.com/kubernetes-sigs/hierarchical-namespaces/issues/292)
+Note: Decimal point values cannot be specified in HRQ (you can't do `cpu: 1.5`, but you can do `cpu: "1.5"` or `cpu: 1500m`). See [#292](https://github.com/kubernetes-sigs/hierarchical-namespaces/issues/292)
 
 <a name="basic-propagation">
 

docs/user-guide/quickstart.md

@@ -461,11 +461,11 @@ kubectl delete pods s2 -n service-2
 
 <a name="hrq"/>
 
-### Hierarchical resource quotas
+### Hierarchical resource quotas (HRQs)
 
 ***Hierarchical resource quotas are beta in HNC v1.1***
 
-***HRQs are not included by default, to use it install the hrq.yaml file in the [releases -> Assets](https://github.com/kubernetes-sigs/hierarchical-namespaces/releases)***
+***HRQs are not included by default. To use it, install the `hrq.yaml` file in [Releases -> Assets](https://github.com/kubernetes-sigs/hierarchical-namespaces/releases)***
 
 _Will demonstrate: Create and delete [HierarchicalResourceQuota](concepts.md#hierarchical-resource-quota)._
 
@@ -476,11 +476,11 @@ acme-org
 └── [s] team-b
 ```
 
-You can create a `HierarchicalResourceQuota` in namespace `acme-org`, and the sum of 
-all subnamespaces resource usage can't go over what is configured in the HRQ.
+If you create a `HierarchicalResourceQuota` in namespace `acme-org`, the sum of
+all subnamespaces' resources can't surpass the HRQ.
 
 We will demonstrate how it works using services, but you could also limit `cpu`,
-`memory` or any other `ResourceQuota` field.
+`memory`, or any other `ResourceQuota` field.
 
 Creating the HRQ:
 ```bash
@@ -525,12 +525,12 @@ acme-org   services: 1/1
 ```
 You can also view HRQs in all namespaces by running `kubectl get hrq -A`.
 
-And finally you can delete the HRQ via simply deleting the CR:
+And finally, you can delete the HRQ via simply deleting the CR:
 ```bash
 kubectl delete hrq acme-org-hrq -n acme-org
 ```
 
-Note: Decimal point values cannot be specified (you can't do `cpu: 1.5` but
+Note: Decimal point values cannot be specified (you can't do `cpu: 1.5`, but
 you can do `cpu: "1.5"` or `cpu: 1500m`). See [#292](https://github.com/kubernetes-sigs/hierarchical-namespaces/issues/292)
 
 <a name="subns"/>