Cache documentation improvements

[AlexanderAshitkin]

Attempt to fix numerous typos, and grammatical errors and improve the overall style and text clarity of the documentation. Addresses documentation comments raised in pr #33

• Make sure there is a JIRA issue filed
  for the change (usually before you start working on it). Trivial changes like typos do not
  require a JIRA issue. Your pull request should address just this issue, without
  pulling in other changes.
• Each commit in the pull request should have a meaningful subject line and body.
• Format the pull request title like [MNG-XXX] - Fixes bug in ApproximateQuantiles,
  where you replace MNG-XXX with the appropriate JIRA issue. Best practice
  is to use the JIRA issue title in the pull request title and in the first line of the
  commit message.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Run mvn clean verify to make sure basic checks pass. A more thorough check will
  be performed on your pull request automatically.
• You have run the Core IT successfully.

If your pull request is about ~20 lines of code you don't need to sign an
Individual Contributor License Agreement if you are unsure
please ask on the developers list.

To make clear that you license your contribution under
the Apache License Version 2.0, January 2004
you have to acknowledge this by using the following check-box.

• I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004

• In any other case, please file an Apache Individual Contributor License Agreement.

[olamy]

?

[AlexanderAshitkin]

Assuming that you ask to clarify the statement above, here's the rationale - the core extension initialization model allows binding core API classes, like lifecycle listeners. Besides that, using the cache as a build-level extension tempts the user to initialize the cache in different parts of the project subtree, which was never intended and likely tested. The core extension is the best way to use the cache, which leaves us the door to use all the internal maven APIs future and aligns well with the caching nature. It's just right to make it the recommended option. Honestly, I would deprecate the build extension mode because it doesn't solve any particular problem and just increases accidental complexity.

Let's merge this PR to improve documentation in the next iterations.

[olamy]

Sounds good.
BUT fyi this issue (https://issues.apache.org/jira/browse/MINVOKER-336) is a real pain. So for projects having some usage of maven-invoker-plugin apart of other modules it is causing some bugs.
This project by example (https://github.com/eclipse/jetty.project/tree/jetty-12.0.x) cannot use .mvn/extensions.xml this otherwise maven plugins its via m-invoker-p are using the cache from top module which is not expected ;)

[olamy]

@gnodet all good now?