[maven-site] branch master updated: [MNGSITE-397] Rewrite and clarify (#149)

[el...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

elharo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git


The following commit(s) were added to refs/heads/master by this push:
     new 06e3053  [MNGSITE-397] Rewrite and clarify (#149)
06e3053 is described below

commit 06e305372be6c1294d16e7ad3a6f681065e586d1
Author: Elliotte Rusty Harold <el...@users.noreply.github.com>
AuthorDate: Tue Mar 31 18:27:06 2020 -0400

    [MNGSITE-397] Rewrite and clarify (#149)
    
    * [MNGSITE-397] Rewrite and clarify
    
    @EPadronU
    
    * Encouraging better development practices
---
 content/markdown/what-is-maven.md | 82 +++++++++++++++------------------------
 1 file changed, 32 insertions(+), 50 deletions(-)

diff --git a/content/markdown/what-is-maven.md b/content/markdown/what-is-maven.md
index a89c18e..6402f62 100644
--- a/content/markdown/what-is-maven.md
+++ b/content/markdown/what-is-maven.md
@@ -17,13 +17,13 @@ KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->
-Maven, a [Yiddish word](https://en.wikipedia.org/wiki/Maven) meaning
+Maven, a Yiddish word meaning
 *accumulator of knowledge*, began as an attempt to
 simplify the build processes in the Jakarta Turbine project. There were
 several projects, each with their own Ant build files, that were all
 slightly different. JARs were checked into CVS. We wanted a standard
 way to build the projects, a clear definition of what the project
-consisted of, an easy way to publish project information and a way to
+consisted of, an easy way to publish project information, and a way to
 share JARs across several projects.
 
 The result is a tool that can now be used for building and managing any
@@ -35,52 +35,44 @@ with the comprehension of any Java-based project.
 
 Maven's primary goal is to allow a developer to comprehend the complete
 state of a development effort in the shortest period of time. In order
-to attain this goal, there are several areas of concern that Maven
-attempts to deal with:
+to attain this goal, Maven deals with several areas of concern:
 
--   Making the build process easy
--   Providing a uniform build system
--   Providing quality project information
--   Providing guidelines for best practices development
--   Allowing transparent migration to new features
+- Making the build process easy
+- Providing a uniform build system
+- Providing quality project information
+- Encouraging better development practices
 
 ### Making the build process easy
 
 While using Maven doesn't eliminate the need to know about the
-underlying mechanisms, Maven does provide a lot of shielding from the
-details.
+underlying mechanisms, Maven does shield developers from many details.
 
 ### Providing a uniform build system
 
-Maven allows a project to be built using its project object model (POM) and
-a set of plugins that are shared by all projects using Maven, providing
-a uniform build system. Once you familiarize yourself with how one Maven
-project builds you automatically know how all Maven projects build
-saving you immense amounts of time when trying to navigate many
-projects.
+Maven builds a project using its project object model (POM) and
+a set of plugins. Once you familiarize yourself with one Maven
+project, you know how all Maven projects build.
+This saves time when navigating many projects.
 
 ### Providing quality project information
 
-Maven provides plenty of useful project information that is in part
+Maven provides useful project information that is in part
 taken from your POM and in part generated from your project's sources.
 For example, Maven can provide:
 
--   Change log document created directly from source control
+-   Change log created directly from source control
 -   Cross referenced sources
--   List of mailing lists managed by the project
--   Dependency list
+-   Mailing lists managed by the project
+-   Dependencies used by the project
 -   Unit test reports including coverage
 
-As Maven improves the information set provided will improve, all of
-which will be transparent to users of Maven.
-
-Other products can also provide Maven plugins to allow their set of
-project information alongside some of the standard information given by
-Maven, all still based on the POM.
+Third party code analysis products also provide Maven plugins that add their
+reports to the standard information given by
+Maven.
 
 ### Providing guidelines for best practices development
 
-Maven aims to gather current principles for best practices development,
+Maven aims to gather current principles for best practices development
 and make it easy to guide a project in that direction.
 
 For example, specification, execution, and reporting of unit tests are
@@ -89,27 +81,27 @@ practices were used as guidelines:
 
 -   Keeping test source code in a separate, but parallel source tree
 -   Using test case naming conventions to locate and execute tests
--   Having test cases setup their environment instead of relying on
+-   Having test cases setup their environment instead of
     customizing the build for test preparation
 
-Maven also aims to assist in project workflow such as release and issue management.
+Maven also assists in project workflow such as release and issue management.
 
 Maven also suggests some guidelines on how to layout your project's
-directory structure. Once you learn the layout you can easily
-navigate any other project that uses Maven and the same defaults.
-
-### Allowing transparent migration to new features
+directory structure. Once you learn the layout, you can easily
+navigate other projects that use Maven.
 
-Maven provides an easy way for Maven clients to update their
-installations so that they can take advantage of any changes that have been
-made to Maven itself.
+While takes an opinionated approach to project layout, some projects
+may not fit with this structure for historical reasons. While Maven is
+designed to be flexible to the needs of different projects,
+it cannot cater to every situation without compromising its objectives.
 
-Installation of new or updated plugins from third parties or Maven
-itself has been made trivial for this reason.
+If your project has an unusual build structure that 
+cannot be reorganized, you may have to forgo some features or the use of
+Maven altogether.
 
 ## What is Maven Not?
 
-You may have heard some of the following things about Maven:
+You might have heard some of the following things about Maven:
 
 -   Maven is a site and documentation tool
 -   Maven extends Ant to let you download dependencies
@@ -119,13 +111,3 @@ While Maven does these things, as you can read above in the "What is
 Maven?" section, these are not the only features Maven has, and its
 objectives are quite different.
 
-Maven does encourage best practices, but we realise that some projects
-may not fit with these ideals for historical reasons. While Maven is
-designed to be flexible, to an extent, in these situations and to the
-needs of different projects, it can not cater to every situation without
-making compromises to the integrity of its objectives.
-
-If you decide to use Maven and have an unusual build structure that you
-cannot reorganise, you may have to forgo some features or the use of
-Maven altogether.
-