docs: improve grammar and simplify HRQ examples

[agilgur5]

Summary

Was reading through the docs and these seemed the most verbose

• it seems to be a very recent feature as well, from HierarchicalResourceQuota documentation #289

Details

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

Grammar

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

Simplifications

• simplify several sentences, per k8s style guide

  • "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"
    • "resource usage" -> "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
  • also remove the word "simply", per style guide

• 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 Documentation for #295 #298
  • they largely duplicated each other with slightly 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

Review Notes

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

• EDIT: See docs: apply k8s style guide to HRQ quickstart example #316 as one follow-up

Misc

This is a great example! It gives very practical, real-world use-cases which is very helpful for context and understanding how one might use HNC!

[k8s-ci-robot]

Hi @agilgur5. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[adrianludwin]

Thanks for this change!

/lgtm
/approve

[adrianludwin]

Hi @agilgur5 , sorry for the long delay, but could you please rebase this change? I think the tests will pass after that's done. Thanks!

[agilgur5]

@adrianludwin rebased. It needs to be re-approved now

[rjbez17]

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: adrianludwin, agilgur5, rjbez17

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [adrianludwin,rjbez17]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[rjbez17]

/lgtm