Rewrite documentation according to ASD-STE100 Simplified Technical En…

src/site/markdown/descriptor-refs.md

@@ -28,38 +28,42 @@ under the License.
 
 # Pre-defined Descriptor Files
 
-There are four predefined descriptor formats available for reuse, packaged within the Assembly Plugin. Their descriptorIds are:
+There are four predefined descriptor formats available for reuse. They are packaged within the Assembly Plugin. Their descriptorIds are:
 
 <!-- MACRO{toc|fromDepth=2|toDepth=2} -->
+
 ## bin
 
-Use `bin` as the `descriptorRef` of your assembly-plugin configuration in order to create a binary distribution archive of your project. This built-in descriptor produces an assembly with the classifier `bin` in three archive formats: tar.gz, tar.bz2, and zip.
+Use `bin` as the `descriptorRef` of your assembly-plugin configuration. This creates a binary distribution archive of your project. The built-in descriptor produces an assembly with the classifier `bin` in three archive formats: tar.gz, tar.bz2, and zip.
 
-The assembled archive contains the binary JAR produced by running `mvn package` plus any README, LICENSE, and NOTICE files available in the project root directory.
+The assembled archive contains the binary JAR produced by running `mvn package`. It also contains any README, LICENSE, and NOTICE files available in the project root directory.
 
 Below is the `bin` descriptor format:
 
 <!-- MACRO{snippet|id=bin|file=target/classes/assemblies/bin.xml} -->
+
 ## jar-with-dependencies
 
-Use `jar-with-dependencies` as the `descriptorRef` of your assembly-plugin configuration in order to create a JAR which contains the binary output of your project, along its the unpacked dependencies. This built-in descriptor produces an assembly with the classifier `jar-with-dependencies` using the JAR archive format.
+Use `jar-with-dependencies` as the `descriptorRef` of your assembly-plugin configuration. This creates a JAR which contains the binary output of your project along with its unpacked dependencies. The built-in descriptor produces an assembly with the classifier `jar-with-dependencies` using the JAR archive format.
 
-Note that `jar-with-dependencies` provides only basic support for uber-jars. For more control, use the [Maven Shade Plugin](https://maven.apache.org/plugins/maven-shade-plugin/).
+The `jar-with-dependencies` descriptor provides only basic support for uber-jars. For more control, use the [Maven Shade Plugin](https://maven.apache.org/plugins/maven-shade-plugin/).
 
 Below is the `jar-with-dependencies` descriptor format:
 
 <!-- MACRO{snippet|id=jar-with-dependencies|file=target/classes/assemblies/jar-with-dependencies.xml} -->
+
 ## src
 
-Use `src` as the `descriptorRef` in your assembly-plugin configuration to create source archives for your project. The archive will contain the contents of your project's `/src` directory structure, for reference by your users. The `src` descriptorId produces an assembly archive with the classifier `src` in three formats: tar.gz, tar.bz2, and zip.
+Use `src` as the `descriptorRef` in your assembly-plugin configuration. This creates source archives for your project. The archive will contain the contents of your project's `/src` directory structure for reference by your users. The `src` descriptorId produces an assembly archive with the classifier `src`. It supports three formats: tar.gz, tar.bz2, and zip.
 
 Below is the `src` descriptor format:
 
 <!-- MACRO{snippet|id=src|file=target/classes/assemblies/src.xml} -->
+
 ## project
 
-Using the `project` `<descriptorRef>` in your Assembly Plugin configuration will produce an assembly containing your entire project, minus any build output that lands in the `/target` directory. The resulting assembly should allow your users to build your project using Maven, Ant, or whatever build system you have configured in your project's normal SCM working directory. It produces assemblies with the classifier `project` in three archive formats: tar.gz, tar.bz2, and zip.
+Using the `project` `<descriptorRef>` in your Assembly Plugin configuration produces an assembly. The assembly contains your entire project, minus any build output that lands in the `/target` directory. The resulting assembly allows your users to build your project using Maven, Ant, or whatever build system you configured in your project's normal SCM working directory. It produces assemblies with the classifier `project` in three formats: tar.gz, tar.bz2, and zip.
 
 The following is the assembly descriptor for the `project` descriptorRef:
 
-<!-- MACRO{snippet|id=project|file=target/classes/assemblies/project.xml} -->
+<!-- MACRO{snippet|id=project|file=target/classes/assemblies/project.xml} -->

src/site/markdown/examples/index.md

@@ -28,7 +28,7 @@ under the License.
 
 ## Table of Contents
 
-Below, you will see a series of examples showing how to use the Assembly Plugin in various contexts.
+Below, you see a series of examples showing how to use the Assembly Plugin in various contexts.
 
 - [Working with Single Projects](./single/index.html)
     - [Filtering Some Distribution Files](./single/filtering-some-distribution-files.html)
@@ -39,4 +39,4 @@ Below, you will see a series of examples showing how to use the Assembly Plugin
     - [Adding Module Sources to the Assembly](./multimodule/module-source-inclusion-simple.html)
     - [Adding Module Binaries to the Assembly](./multimodule/module-binary-inclusion-simple.html)
 - [Sharing Assembly Descriptors](./sharing-descriptors.html)
-- [Using Inline Assembly Descriptors](./using-inline-descriptors.html)
+- [Using Inline Assembly Descriptors](./using-inline-descriptors.html)

src/site/markdown/examples/multimodule/index.md

@@ -28,7 +28,7 @@ under the License.
 
 Multimodule Projects use <moduleSets> in their assemblies.
 
-The examples below may be able to help you when creating assemblies for your multimodule project.
+The examples below can help you create assemblies for multimodule projects.
 
 - [Adding Module Sources to the Assembly](./module-source-inclusion-simple.html)
 - [Adding Module Binaries to the Assembly](./module-binary-inclusion-simple.html)

src/site/markdown/examples/multimodule/module-binary-inclusion-simple.md.vm

@@ -26,29 +26,32 @@ under the License.
 
 # Including Module Binaries
 
-Warning
--------
+## Warning
 
-**Warning:** Using the `binaries` section of a `moduleSet` definition involves some tricky considerations that are a result of the way Maven sorts and executes project builds within a multimodule context. Please read [this FAQ entry](../../faq.html#module-binaries) if you decide to use them.
+**Warning:** Using the `binaries` section of a `moduleSet` definition is tricky.
+These are a result of the way Maven sorts and executes project builds within a multimodule context.
+Read [this FAQ entry](../../faq.html#module-binaries) if you decide to use them.
 
-**NOTE:** The new `useAllReactorProjects` flag in the `moduleSet` section allows you to consume module binaries from child modules in a multimodule build. This is an important to resolve the conflict between Maven's build ordering and the old approach to module binaries, where the assembly was build from the parent POM. Please read the FAQ entry above for more information, and read the documentation below (carefully!) to see the new approach in action.
+**NOTE:** The new `useAllReactorProjects` flag in the `moduleSet` section allows you to consume module binaries from child modules in a multimodule build.
+This is important to resolve the conflict between Maven's build ordering and the old approach to module binaries.
+The old approach built the assembly from the parent POM.
+Read the FAQ entry above for more information, and read the documentation below to see the new approach in action.
 
-Introduction
-------------
+## Introduction
 
-It is common practice to create an assembly using the parent POM of a multimodule build. At times, you may want to ensure that this assembly also includes one or more of the module binaries.
+It is common practice to create an assembly using the parent POM of a multimodule build. 
+At times, you may want this assembly to also include one or more of the module binaries.
 
 This example demonstrates how to include the artifact and dependencies of a module, under the directory `modules/<module-name>`.
 
-The Assembly Descriptor
------------------------
+## The Assembly Descriptor
 
-First, let's write an assembly descriptor to create this assembly. For the sake of clarity, this descriptor will be as simple as possible, only demonstrating the features described by this example.
+This is an assembly descriptor that can create this assembly. It is as simple as possible, only demonstrating the features described by this example.
 
 ```xml
 <assembly xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
+    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} https://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
   <id>bin</id>
   <formats>
     <format>dir</format>
@@ -73,16 +76,19 @@ First, let's write an assembly descriptor to create this assembly. For the sake
 </assembly>
 ```
 
-This descriptor states that the assembly id should be `bin`, that the output format is a directory, and that the contents of the assembly should **not** be contained within a directory named after the finalName of the top-level project.
+This descriptor states that the assembly id is `bin`, that the output format is a directory,
+and that the contents of the assembly must **not** be contained within a directory named after the finalName of the top-level project.
 
-Furthermore, it states that we wish to include the artifact files for the module with a groupId of `org.test` and an artifactId of `child1`, along with its dependency artifacts. These artifacts should be contained within the directory structure `modules/child1` for this module, since the outputDirectory expression will be interpolated on a module-by-module basis.
+Furthermore, it states that the assembly will include the artifact files for the module with a groupId of `org.test` and an artifactId of `child1`,
+along with its dependency artifacts. These artifacts must be contained within the directory structure `modules/child1` for this module,
+since the outputDirectory expression will be interpolated on a module-by-module basis.
 
-**Finally**, notice the **new** `useAllReactorProjects` flag. This enables access to all projects in the current reactor (multimodule build), even from a child module. Using this flag, it's now possible to use a child module - sorted to the end of the multimodule build process using appropriate dependency declarations - to generate an assembly containing module binaries.
+**Finally**, notice the **new** `useAllReactorProjects` flag. This enables access to all projects in the current reactor (multimodule build), even from a child module.
+Using this flag, a child module (sorted to the end of the multimodule build process using appropriate dependency declarations) can generate an assembly containing module binaries.
 
-The POM
--------
+## The POM
 
-Now, let's review the POM configuration necessary to enable the building of this assembly via the `assembly:single` goal. First, let's look at the parent POM:
+Now, review the POM configuration necessary to build this assembly via the `assembly:single` goal. First, look at the parent POM:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -123,7 +129,7 @@ Now, let's review the POM configuration necessary to enable the building of this
 </project>
 ```
 
-**NOTE:** The last module - `distribution` - is the child in which the assembly will be created.
+**NOTE:** The last module (`distribution`) is the child in which the assembly will be created.
 
 That POM looks like this:
 
@@ -184,25 +190,26 @@ That POM looks like this:
 </project>
 ```
 
-This POM directs the Assembly Plugin to execute the `single` goal when the build reaches the `package` phase, and tells it to use the `bin.xml` assembly descriptor when executing.
+This POM directs the Assembly Plugin to execute the `single` goal when the build reaches the `package` phase.
+It tells the plugin to use the `bin.xml` assembly descriptor when executing.
 
-Execute!
----------
+## Execute!
 
-To build the assembly, we issue the following command:
+To build the assembly, run the following command:
 
 ```
 mvn clean package
 ```
 
-This will ensure that the output directory (normally, `target`), is removed before building the assembly directory.
+This removes the output directory (normally, `target`) before building the assembly directory.
 
-**Note:** Because of a quirk in Maven 2.0's execution model relating to aggregator goals and the inheritance hierarchy, we need to explicitly execute the package phase ahead of the assembly invocation, to ensure all modules have been built.
+**Note:** Because of a quirk in Maven 2.0's execution model relating to aggregator goals and the inheritance hierarchy, we need to explicitly execute the package phase ahead of the assembly invocation.
+This ensures all modules have been built.
 
-Examining the Output
---------------------
+## Examining the Output
 
-When the Maven execution completes, the following directory structure should be left. Remember, our assembly format was `dir`, which is why the output is a directory and not an archive of some sort.
+When the Maven execution completes, the following directory structure is left.
+Remember, the assembly format was `dir`, which is why the output is a directory and not an archive of some sort.
 
 Here are the directory contents:
 

src/site/markdown/examples/multimodule/module-source-inclusion-simple.md.vm

@@ -26,17 +26,16 @@ under the License.
 
 # Including Module Sources
 
-Introduction
-------------
+## Introduction
 
-It is common practice to create an assembly using the parent POM of a multimodule build. At times, you may want to ensure that this assembly also includes the source code from one or more of the modules in this build.
+It is common practice to create an assembly using the parent POM of a multimodule build.
+At times, you may this assembly to also include the source code from one or more of the modules in this build.
 
 This example demonstrates how to include the project sources from a module in the project assembly, under the directory `sources/<module-name>`.
 
-The Assembly Descriptor
------------------------
+## The Assembly Descriptor
 
-First, let's write an assembly descriptor to create this assembly. For the sake of clarity, this descriptor will be as simple as possible, only demonstrating the features described by this example.
+First, write an assembly descriptor to create this assembly. For clarity, this descriptor is as simple as possible, only demonstrating the features described by this example.
 
 ```xml
 <assembly xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
@@ -69,18 +68,17 @@ First, let's write an assembly descriptor to create this assembly. For the sake
 </assembly>
 ```
 
-This descriptor states that the assembly id should be `src`, that the output format is a directory, and that the contents of the assembly should **not** be contained within a directory named after the finalName of the top-level project.
+This descriptor states that the assembly id is `src`, that the output format is a directory, and that the contents of the assembly must **not** be contained within a directory named after the finalName of the top-level project.
 
-Furthermore, it states that we wish to include the source files for the module with a groupId of `org.test` and an artifactId of `child1`. These sources should be contained within the directory structure `sources/child1` for this module, since the outputDirectory expression will be interpolated on a module-by-module basis.
+Furthermore, it states that we wish to include the source files for the module with a groupId of `org.test` and an artifactId of `child1`. These sources must be contained within the directory structure `sources/child1` for this module, since the outputDirectory expression is interpolated on a module-by-module basis.
 
-By default, the Assembly Plugin will add the sources under a folder named with the artifactId of each module; this can be disabled by setting `includeModuleDirectory` to `false`.
+By default, the Assembly Plugin adds the sources in a folder named with the artifactId of each module. This can be disabled by setting `includeModuleDirectory` to `false`.
 
-Note that the build directory (`target` by default) will be included, so it is explicitly excluded since this is a temporary storage for files produced during the build and it should not contain any project sources.
+The build directory is included by default, so it is explicitly excluded since this is a temporary storage for files produced during the build and it must not contain any project sources.
 
-The POM
--------
+## The POM
 
-Now, let's review the POM configuration necessary to enable the building of this assembly via the _assembly:single_ goal:
+Now, review the POM configuration necessary to build of this assembly via the _assembly:single_ goal:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -118,23 +116,21 @@ Now, let's review the POM configuration necessary to enable the building of this
 </project>
 ```
 
-This POM simply directs the Assembly Plugin to use the `src.xml` assembly descriptor when executing.
+This POM directs the Assembly Plugin to use the `src.xml` assembly descriptor when executing.
 
-Execute!
----------
+## Execute!
 
-To build the assembly, we issue the following command:
+To build the assembly, run the following command:
 
 ```shell
 mvn clean assembly:single
 ```
 
-This will ensure that the output directory (normally, `target`), is removed before building the assembly directory.
+This rmeoves the output directory (normally, `target`) before building the assembly directory.
 
-Examining the Output
---------------------
+## Examining the Output
 
-When the Maven execution completes, the following directory structure should be left:
+When the Maven execution completes, the following directory structure is left:
 
 ```unknown
 target/parent-1.0-src/