diff --git a/docs/user-guide/concepts.md b/docs/user-guide/concepts.md
index e58e2664d..328d72550 100644
--- a/docs/user-guide/concepts.md
+++ b/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)
diff --git a/docs/user-guide/quickstart.md b/docs/user-guide/quickstart.md
index e00d92f82..f5a9cddb1 100644
--- a/docs/user-guide/quickstart.md
+++ b/docs/user-guide/quickstart.md
@@ -461,11 +461,11 @@ kubectl delete pods s2 -n service-2
-### 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 by 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)