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-checkstyle-plugin.git


The following commit(s) were added to refs/heads/master by this push:
     new 1170aa3  Rewrite site documentation in Simplified Technical English 
(#719)
1170aa3 is described below

commit 1170aa3c8721b7b7c32c3c8ca5afc47ba14af968
Author: Elliotte Rusty Harold <[email protected]>
AuthorDate: Tue Nov 10 20:49:04 2026 +0000

    Rewrite site documentation in Simplified Technical English (#719)
    
    Rewrite the prose in the site markdown pages according to
    ASD-STE100 Simplified Technical English. Use simple tenses, active
    voice, imperative mood for instructions, and the approved modals.
    Remove contractions, semicolons, and -ing verb forms from the prose.
    Align the site menu labels with the new page titles.
---
 src/site/markdown/config/index.md                  |  5 +-
 .../markdown/examples/custom-checker-config.md.vm  | 15 +++---
 .../examples/custom-developed-checkstyle.md.vm     | 62 ++++++++++++++--------
 .../examples/custom-property-expansion.md.vm       | 19 ++++---
 .../markdown/examples/inline-checker-config.md.vm  | 23 ++++----
 .../markdown/examples/multi-module-config.md.vm    | 36 ++++++++-----
 .../markdown/examples/suppressions-filter.md.vm    | 10 ++--
 .../markdown/examples/upgrading-checkstyle.md.vm   | 11 ++--
 src/site/markdown/faq.md                           | 33 ++++++------
 src/site/markdown/index.md.vm                      | 51 ++++++++++++------
 src/site/markdown/usage.md.vm                      | 31 +++++++----
 src/site/site.xml                                  | 12 ++---
 12 files changed, 195 insertions(+), 113 deletions(-)

diff --git a/src/site/markdown/config/index.md 
b/src/site/markdown/config/index.md
index 8236161..021fddb 100644
--- a/src/site/markdown/config/index.md
+++ b/src/site/markdown/config/index.md
@@ -27,7 +27,10 @@ under the License.
 
 # Predefined Rulesets
 
-Maven Checkstyle Plugin has had different sets of predefined rulesets across 
different versions. Some have been included in the plugin itself while others 
have been references to other projects. The table below shows this history.
+Maven Checkstyle Plugin had different sets of predefined rulesets across 
different versions.
+Some rulesets were included in the plugin itself.
+Other rulesets were references to other projects.
+The table below shows this history.
 
 |Predefined ruleset|2.0 - 2.13|2.14|2.15|2.16 -|
 |:---|:---|:---|:---|:---|
diff --git a/src/site/markdown/examples/custom-checker-config.md.vm 
b/src/site/markdown/examples/custom-checker-config.md.vm
index b55021c..5e00f38 100644
--- a/src/site/markdown/examples/custom-checker-config.md.vm
+++ b/src/site/markdown/examples/custom-checker-config.md.vm
@@ -1,5 +1,5 @@
 ---
-title: Using a Custom Checkstyle Checker Configuration
+title: Custom Checkstyle Checker Configuration
 author: 
   - 2015-05-01
 ---
@@ -23,11 +23,12 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Using a Custom Checkstyle Checker Configuration
+# Custom Checkstyle Checker Configuration
 
-A custom [Checker configuration xml 
file](https://checkstyle.org/config.html#Checker) can be defined and then 
referenced via a URL, File, or build classpath resource reference.
+You can define a custom [Checker configuration xml 
file](https://checkstyle.org/config.html#Checker).
+You can reference it through a URL, a file, or a build classpath resource.
 
-To reference a custom Checkstyle Checker configuration, use the 
`configLocation` parameter.
+Use the `configLocation` parameter to reference a custom Checkstyle Checker 
configuration.
 
 ```xml
 <project>
@@ -48,9 +49,11 @@ To reference a custom Checkstyle Checker configuration, use 
the `configLocation`
 </project>
 ```
 
-This example causes the Checkstyle Plugin to check for a File named 
`checkstyle.xml` or a resource named `checkstyle.xml` within the compile scope 
of the dependencies or build extensions classpath.
+This example makes the plugin check for a file named `checkstyle.xml`.
+It can find the file in the compile scope of the dependencies or in the build 
extensions classpath.
 
-There are 2 predefined Checkstyle configuration definitions that ship with the 
Checkstyle Plugin, the Sun Microsystems Definition is selected by default.
+The Checkstyle Plugin ships with two predefined configuration definitions.
+It selects the Sun Microsystems definition by default.
 
 - **sun_checks.xml** - Sun Microsystems Definition (default).
 - **google_checks.xml** - Google Definition.
diff --git a/src/site/markdown/examples/custom-developed-checkstyle.md.vm 
b/src/site/markdown/examples/custom-developed-checkstyle.md.vm
index d64273a..b5002aa 100644
--- a/src/site/markdown/examples/custom-developed-checkstyle.md.vm
+++ b/src/site/markdown/examples/custom-developed-checkstyle.md.vm
@@ -1,5 +1,5 @@
 ---
-title: Using Custom Developed Checkstyle Checks
+title: Custom Developed Checkstyle Checks
 author: 
   - 2008-02-04
 ---
@@ -23,18 +23,22 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Using Custom Developed Checkstyle Checks
+# Custom Developed Checkstyle Checks
 
-We will guide you through creating a Maven project that produces a jar file of 
your custom checks. Then we'll include it in one of your projects by adding it 
as a dependency to the Checkstyle Plugin.
+This example shows how to create a Maven project for your custom checks.
+The project generates a jar file.
+You then use the jar file in your other projects.
+You add the jar file as a dependency to the Checkstyle Plugin.
 
-The plugin also provides the ability to define the [package names XML 
document](https://checkstyle.org/config.html#Packages) required to reference 
your custom check modules more easily.
+The plugin also lets you define the [package names XML 
document](https://checkstyle.org/config.html#Packages).
+This document lets Checkstyle reference your custom check modules.
 
-In this example we will be using the [example 
check](https://checkstyle.org/writingchecks.html#Visitor_in_action) that can be 
found on the Checkstyle web site.
+This example uses the [example 
check](https://checkstyle.org/writingchecks.html#Visitor_in_action) from the 
Checkstyle website.
 
-Structuring your project
-------------------------
+Project Structure
+-----------------
 
-First we set up the directory structure for the custom checks project. It 
looks like this:
+This project has the directory structure below:
 
 ```text
 mycompany-checkstyle-checks
@@ -49,11 +53,11 @@ mycompany-checkstyle-checks
                         `-- MethodLimitCheck.java
 ```
 
-Now we'll go through each of the three files one at a time.
+The sections below describe the three files.
 
 #[[### `pom.xml`]]#
 
-Not much to say here, except that we add a dependency on Checkstyle.
+This POM adds a dependency on Checkstyle.
 
 ```xml
 <project>
@@ -74,7 +78,10 @@ Not much to say here, except that we add a dependency on 
Checkstyle.
 
 #[[### `packagenames.xml`]]#
 
-This file lets you specify the names of the packages that you want to be able 
to use. Here we have added `com.mycompany.checks` to the standard set of 
Checkstyle packages. That means that you can use your custom checks in the 
Checkstyle configuration file, without having to specify their package name.
+This file lets you specify the names of the packages that you want to use.
+This example adds `com.mycompany.checks` to the standard set of Checkstyle 
packages.
+You can then use your custom checks in the Checkstyle configuration file.
+You do not need to specify their package name.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -109,7 +116,8 @@ This file lets you specify the names of the packages that 
you want to be able to
 
 #[[### `MethodLimitCheck.java`]]#
 
-Here is the example check from the Checkstyle site. It checks that your source 
files don't have more that 30 methods.
+Here is the example check from the Checkstyle site.
+It checks that your source files do not have more than 30 methods.
 
 ```java
 package com.mycompany.checks;
@@ -140,16 +148,18 @@ public class MethodLimitCheck extends Check
 }
 ```
 
-Building a JAR for your custom checks project
----------------------------------------------
+Build the JAR for Your Custom Checks Project
+--------------------------------------------
 
-To be able to use your custom checks in other projects, you need to package 
and install them. To do that, just run this on the command line:
+To use your custom checks in other projects, package and install them.
+Run this command:
 
 ```shell
 mvn install
 ```
 
-This produces a JAR file with the following contents and installs it into your 
local repository.
+This command produces a JAR file with these contents.
+It also installs the file into your local repository.
 
 #[[### `mycompany-checkstyle-checks-1.0.jar`]]#
 
@@ -170,16 +180,18 @@ mycompany-checkstyle-checks-1.0.jar
             `-- MethodLimitCheck.class
 ```
 
-Using your checks in another project
-------------------------------------
+Use Your Checks in Another Project
+----------------------------------
 
-Now you are ready to make use of your custom checks in another project.
+You are now ready to use your custom checks in another project.
 
 #[[### Create a Checkstyle configuration]]#
 
-Create the file `checkstyle.xml` in the root of the project that wants to use 
your custom checks. In this file you tell Checkstyle which checks you want to 
use.
+Create the file `checkstyle.xml` in the root of the project that wants to use 
your custom checks.
+In this file, tell Checkstyle which checks you want to use.
 
-**Note:** We don't have to specify the fully qualified classname of our check 
here. That's because we used the `packagenames.xml` file earlier.
+**Note:** You do not have to specify the fully qualified class name of your 
check here.
+The `packagenames.xml` file makes this possible.
 
 ```xml
 <?xml version="1.0" ?>
@@ -197,9 +209,13 @@ Create the file `checkstyle.xml` in the root of the 
project that wants to use yo
 
 #[[### Configure the Checkstyle Plugin to use your custom checks]]#
 
-Finally we need to tell the other project that you want it to use your custom 
Checkstyle checks. In the `pom.xml` of that project, add the following 
configuration.
+Finally, tell the other project to use your custom Checkstyle checks.
+Add this configuration to the `pom.xml` of that project.
 
-**Note:** You have to specify a plugin dependency on 
`mycompany-checkstyle-checks` in the `<build>` element of your `pom.xml`. It 
will not work inside the `<reporting>` element, because `<reporting>` does not 
support plugin dependencies. The rest of the configuration is done in the 
normal way in the `<reporting>` element.
+**Note:** You must specify a plugin dependency on 
`mycompany-checkstyle-checks` in the `<build>` element of your `pom.xml`.
+This dependency will not work in the `<reporting>` element.
+The `<reporting>` element does not support plugin dependencies.
+Do the rest of the configuration in the normal way in the `<reporting>` 
element.
 
 ```xml
 <project>
diff --git a/src/site/markdown/examples/custom-property-expansion.md.vm 
b/src/site/markdown/examples/custom-property-expansion.md.vm
index b6dc1d6..4c35d21 100644
--- a/src/site/markdown/examples/custom-property-expansion.md.vm
+++ b/src/site/markdown/examples/custom-property-expansion.md.vm
@@ -1,5 +1,5 @@
 ---
-title: Using Custom Checkstyle Property Expansion Definitions
+title: Custom Checkstyle Property Expansion Definitions
 author: 
   - 2006-07-21
 ---
@@ -23,13 +23,16 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Using Custom Checkstyle Property Expansion Definitions
+# Custom Checkstyle Property Expansion Definitions
 
-Custom [property expansion 
definitions](https://checkstyle.org/config.html#Properties) for the Checker can 
be defined.
+You can define custom [property expansion 
definitions](https://checkstyle.org/config.html#Properties) for the Checker.
 
-Checkstyle uses the property expansion mechanism to allow injection of 
specific values into a pre-defined Checker configuration. Using property 
expansion alone is an insufficient means to customize the checks performed by 
Checkstyle.
+Checkstyle uses the property expansion mechanism to inject specific values 
into a pre-defined Checker configuration.
+Property expansion alone is not enough to customize the checks that Checkstyle 
performs.
 
-Example: `checkstyle.xml` - only checks the package name in use to ensure that 
it conforms to the desired scheme, but allows for users of this Checker to 
specify their own projectname.
+Example: `checkstyle.xml` - This configuration checks the package name in use.
+It makes sure that the package name conforms to the desired scheme.
+It also lets the Checker users specify their own projectname.
 
 ```xml
 <?xml version="1.0" ?>
@@ -48,7 +51,8 @@ Example: `checkstyle.xml` - only checks the package name in 
use to ensure that i
 </module>
 ```
 
-Example: `pom.xml` - Specifies the `projectname` property expansion that 
Checkstyle will use when encountering such a variable in the above Checker 
configuration.
+Example: `pom.xml` - This configuration specifies the `projectname` property 
expansion.
+Checkstyle uses it when it encounters the variable in the Checker 
configuration above.
 
 ```xml
 <project>
@@ -73,7 +77,8 @@ Example: `pom.xml` - Specifies the `projectname` property 
expansion that Checkst
 </project>
 ```
 
-The property expansion information can also come from a location using the 
`propertiesLocation` parameter as shown below. The `propertiesLocation` can 
point to a URL, File or build classpath resource reference.
+You can also provide the property expansion information from a location with 
the `propertiesLocation` parameter as shown below.
+The parameter can point to a URL, a file, or a build classpath resource.
 
 ```xml
 <project>
diff --git a/src/site/markdown/examples/inline-checker-config.md.vm 
b/src/site/markdown/examples/inline-checker-config.md.vm
index 36d180a..eef312b 100644
--- a/src/site/markdown/examples/inline-checker-config.md.vm
+++ b/src/site/markdown/examples/inline-checker-config.md.vm
@@ -1,5 +1,5 @@
 ---
-title: Using an 'inlined' Checkstyle Checker Configuration
+title: Inline Checkstyle Checker Configuration
 author: 
   - 2015-10-04
 ---
@@ -23,13 +23,15 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Using an Inline Checkstyle Checker Configuration
+# Inline Checkstyle Checker Configuration
 
-Since version 2.12, an inlined [Checker 
configuration](https://checkstyle.org/config.html#Checker) can be defined 
directly in the `configuration` section of the plugin itself inside your 
`pom.xml`.
+From version 2.12, you can define an inline [Checker 
configuration](https://checkstyle.org/config.html#Checker) directly in the 
`configuration` section of the plugin inside your `pom.xml`.
 
-This is especially useful when the Checkstyle checks should be executed with 
every compile and you do not like to create an own project for your Checkstyle 
rules and neither like to have a separate parent POM structure.
+This is useful when you want to run the Checkstyle checks with every compile.
+You do not need to create a separate project for your Checkstyle rules.
+You do not need a separate parent POM structure.
 
-To define a custom Checkstyle checker configuration inside your `pom.xml`, use 
the `checkstyleRules` parameter.
+Use the `checkstyleRules` parameter to define a custom Checkstyle checker 
configuration inside your `pom.xml`.
 
 ```xml
 <project>
@@ -81,13 +83,16 @@ To define a custom Checkstyle checker configuration inside 
your `pom.xml`, use t
 </project>
 ```
 
-# Using a different header
+# Different Header
 
-The inline configuration works by writing the configuration to a file and 
passing that file to checkstyle. This configuration file must contain a 
specific 
[header](https://checkstyle.org/config.html#Configuration_XML_Structure).
+The plugin writes the inline configuration to a file.
+It then passes the file to checkstyle.
+The configuration file must contain a specific 
[header](https://checkstyle.org/config.html#Configuration_XML_Structure).
 
-We include one by default that is compatible with the included checkstyle 
version.
+The plugin includes one by default.
+The default header is compatible with the included checkstyle version.
 
-When you use a different checkstyle version than the the one that's included 
it might be necessary for you to specify a different header:
+When you use a different checkstyle version than the one that is included, you 
must specify a different header:
 
 ```xml
 <project>
diff --git a/src/site/markdown/examples/multi-module-config.md.vm 
b/src/site/markdown/examples/multi-module-config.md.vm
index 88ffb56..3407633 100644
--- a/src/site/markdown/examples/multi-module-config.md.vm
+++ b/src/site/markdown/examples/multi-module-config.md.vm
@@ -25,11 +25,13 @@ under the License.
 
 # Multimodule Configuration
 
-Since version 2.12 of this Plugin you can also 
[inline](./inline-checker-config.html) the configuration directly in the parent 
pom.
+From version 2.12 of this Plugin, you can 
[inline](./inline-checker-config.html) the configuration directly in the parent 
POM.
 
-Configuring the Checkstyle Plugin for use within large multimodule projects 
can be done, but it requires a little setup.
+You can configure the Checkstyle Plugin for large multimodule projects.
+It requires some setup.
 
-This example will use a mysterious project called _whizbang_. This is what the 
structure of that project looks like:
+This example uses a sample project called _whizbang_.
+The project has the structure below:
 
 ```text
 whizbang
@@ -46,7 +48,11 @@ whizbang
 Create a subproject to house the resources
 ------------------------------------------
 
-We'll start by adding another sub project that will house our common 
configuration. Let's call it _build-tools_. In it we put the resources that we 
want to include. In this example, we will add configuration files for the 
Checkstyle Plugin. Configuration files for other plugins, like the PMD plugin, 
can be included in the same subproject if you like.
+Create another subproject that houses your common configuration.
+Call it _build-tools_.
+Put the resources that you want to include in the subproject.
+In this example, add configuration files for the Checkstyle Plugin.
+You can also include configuration files for other plugins, like the PMD 
plugin, in the same subproject.
 
 ```text
 whizbang
@@ -65,9 +71,9 @@ whizbang
 `-- src
 ```
 
-**Tip:** put the resources into a subdirectory that you can ensure will be 
unique and not conflict with anyone else.
+**Tip:** Put the resources into a unique subdirectory so that they do not 
conflict with anyone else.
 
-The `pom.xml` file for _build-tools_ should look like this:
+The `pom.xml` file for _build-tools_ looks like this:
 
 ```xml
 <project>
@@ -82,9 +88,12 @@ The `pom.xml` file for _build-tools_ should look like this:
 Configure the other projects to use it
 --------------------------------------
 
-Now we can include the Checkstyle configuration in the top level `pom.xml`.
+Now include the Checkstyle configuration in the top level `pom.xml`.
 
-**Note:** You have to specify a plugin dependency on `build-tools` in the 
`<build>` element of your `pom.xml`. It will not work inside the `<reporting>` 
element, because `<reporting>` does not support plugin dependencies. The rest 
of the configuration is done in the normal way in the `<reporting>` element.
+**Note:** You must specify a plugin dependency on `build-tools` in the 
`<build>` element of your `pom.xml`.
+This dependency will not work in the `<reporting>` element.
+The `<reporting>` element does not support plugin dependencies.
+Do the rest of the configuration in the normal way in the `<reporting>` 
element.
 
 ```xml
 <project>
@@ -132,14 +141,17 @@ Now we can include the Checkstyle configuration in the 
top level `pom.xml`.
 </project>
 ```
 
-Once you are done with that, ensure that you do not include the Maven 
Checkstyle Plugin in your sub modules, as their definition and configuration, 
will override the top level parent pom's definition.
+Make sure that you do not include the Maven Checkstyle Plugin in your 
submodules.
+A submodule definition overrides the top level parent POM definition.
 
-Based on the Checkstyle Plugin configuration above, the values of 
`configLocation` and `headerLocation` will be resolved from the classpath. The 
_build-tools_ JAR was included in the classpath when it was declared as a 
dependency to the plugin.
+The plugin resolves the values of `configLocation` and `headerLocation` from 
the classpath.
+The _build-tools_ JAR is in the classpath.
+You declared the JAR as a dependency to the plugin.
 
-Lastly, kick off a build of the site.
+Then run a build of the site:
 
 ```shell
 mvn site
 ```
 
-Every sub project will now use the same Checkstyle setup and configuration.
+Every subproject now uses the same Checkstyle setup and configuration.
diff --git a/src/site/markdown/examples/suppressions-filter.md.vm 
b/src/site/markdown/examples/suppressions-filter.md.vm
index 9f9d112..0a9c0a0 100644
--- a/src/site/markdown/examples/suppressions-filter.md.vm
+++ b/src/site/markdown/examples/suppressions-filter.md.vm
@@ -1,5 +1,5 @@
 ---
-title: Using a Suppressions Filter
+title: Suppressions Filter
 author: 
   - 2006-07-21
 ---
@@ -23,9 +23,11 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Using a Suppressions Filter
+# Suppressions Filter
 
-Checkstyle allows the definition of a list of files and their line ranges that 
should be suppressed from reporting any violations (known as a [suppressions 
filter](https://checkstyle.org/config.html#Filters) ).
+Checkstyle lets you define a list of files and their line ranges.
+Checkstyle does not report violations in these ranges.
+This list is called a [suppressions 
filter](https://checkstyle.org/config.html#Filters).
 
 Example: `checkstyle-suppressions.xml`
 
@@ -46,7 +48,7 @@ Example: `checkstyle-suppressions.xml`
 </suppressions>
 ```
 
-Example: `pom.xml` - Specifies the suppressions filter that Checkstyle should 
use.
+Example: `pom.xml` - This configuration specifies the suppressions filter for 
Checkstyle.
 
 ```xml
 <project>
diff --git a/src/site/markdown/examples/upgrading-checkstyle.md.vm 
b/src/site/markdown/examples/upgrading-checkstyle.md.vm
index 802ed00..58f99c4 100644
--- a/src/site/markdown/examples/upgrading-checkstyle.md.vm
+++ b/src/site/markdown/examples/upgrading-checkstyle.md.vm
@@ -1,5 +1,5 @@
 ---
-title: Upgrading Checkstyle at Runtime
+title: Upgrade Checkstyle at Runtime
 author: 
   - 2022-02-07
 ---
@@ -23,11 +23,14 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Upgrading Checkstyle at Runtime
+# Upgrade Checkstyle at Runtime
 
-Maven Checkstyle plugin comes with a default Checkstyle version: for 
`maven-checkstyle-plugin ${project.version}`, Checkstyle ${checkstyleVersion} 
is used by default.
+The Maven Checkstyle Plugin has a default Checkstyle version.
+For `maven-checkstyle-plugin ${project.version}`, the plugin uses Checkstyle 
${checkstyleVersion} by default.
 
-Given Checkstyle generally keeps good compatibility between versions, you can 
override the version used at runtime to benefit from [Checkstyle latest 
bugfixes](https://checkstyle.org/releasenotes.html):
+Checkstyle keeps good compatibility between versions.
+You can override the version used at runtime.
+This lets you use the [latest Checkstyle bug 
fixes](https://checkstyle.org/releasenotes.html):
 
 ```xml
 <project>
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 74eecac..ac60f6c 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -33,40 +33,41 @@ under the License.
 
 <a id="Where_is_maven_checks.xml_predefined_ruleset"></a>
 
-### Where is `config/maven_checks.xml` predefined ruleset?
+### Where is the `config/maven_checks.xml` predefined ruleset?
 
-Starting with maven-checkstyle-plugin version 2.14, `config/maven_checks.xml`
-predefined ruleset is not part of the plugin any more but has moved to
-[Apache Maven Shared Resources](/shared/maven-shared-resources/).
+From maven-checkstyle-plugin version 2.14, `config/maven_checks.xml`
+is no longer part of the plugin.
+The file moved to [Apache Maven Shared 
Resources](/shared/maven-shared-resources/).
 
 <a id="How_are_the_Checkstyle_properties_set"></a>
 
 ### How are the Checkstyle properties set?
 
-You can set the Checkstyle properties to be used in the plugin configuration 
of your
-POM through the `propertiesLocation` parameter. The properties file will be 
resolved
-by the plugin based on its value.
+You can set the Checkstyle properties with the `propertiesLocation` parameter 
in the
+plugin configuration of your POM.
+The plugin resolves the properties file from the value of the parameter.
 
 <a id="How_do_I_set_a_custom_ruleset"></a>
 
 ### How do I set a custom ruleset?
 
-You can set a custom ruleset through the `configLocation` plugin parameter. If 
no
-value is specified, the plugin will use a default ruleset, which is the
-`sun_checks.xml`, that is bundled with the plugin.
+You can set a custom ruleset with the `configLocation` plugin parameter.
+If you do not specify a value, the plugin uses the `sun_checks.xml` ruleset.
+This ruleset is bundled with the plugin.
 
 <a id="How_do_I_include_the_test_directory_in_Checkstyle"></a>
 
 ### How do I include the test directory in Checkstyle?
 
-You can include the test directory in the Checkstyle report by setting the
-`includeTestSourceDirectory` plugin parameter to `true`.
+You can include the test directory in the Checkstyle report.
+The `includeTestSourceDirectory` plugin parameter must be `true`.
 
 <a 
id="What_is_the_difference_between_checkstyle.3Acheckstyle_and_checkstyle.3Acheck"></a>
 
 ### What is the difference between checkstyle:checkstyle and checkstyle:check?
 
-The checkstyle:checkstyle goal is a **reporting** goal that adds a report of
-Checkstyle violations to the output of the maven-site-plugin. The 
checkstyle:check
-goal is an ordinary goal that reports violations to the console and/or fails 
the
-build when there are violations.
+The checkstyle:checkstyle goal is a **reporting** goal.
+It adds a report of Checkstyle violations to the output of the 
maven-site-plugin.
+The checkstyle:check goal is an ordinary goal.
+It reports violations to the console.
+It fails the build when there are violations.
diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index 5786c52..b93c967 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -26,11 +26,16 @@ under the License.
 
 # ${project.name}
 
-The Checkstyle Plugin generates a report regarding the code style used by the 
developers. For more information about Checkstyle, see 
[https://checkstyle.org/](https://checkstyle.org/).
+The Checkstyle Plugin generates a report on the code style used by the 
developers.
+For more information about Checkstyle, see 
[https://checkstyle.org/](https://checkstyle.org/).
 
-This version of the plugin uses Checkstyle ${checkstyleVersion} by default and 
requires Java ${javaVersion}. But you can [upgrade the version used at 
runtime](./examples/upgrading-checkstyle.html).
+This version of the plugin uses Checkstyle ${checkstyleVersion} by default.
+It requires Java ${javaVersion}.
+You can [upgrade the version used at 
runtime](./examples/upgrading-checkstyle.html).
 
-The plugin can be configured in the project's POM. Predefined rulesets 
available for use in this version of the plugin are: 
[`sun_checks.xml`](https://checkstyle.org/sun_style.html) and 
[`google_checks.xml`](https://checkstyle.org/google_style.html). You can also 
use a custom ruleset by specifying it in the plugin configuration.
+The plugin can be configured in the project's POM.
+This version of the plugin provides two predefined rulesets: 
[`sun_checks.xml`](https://checkstyle.org/sun_style.html) and 
[`google_checks.xml`](https://checkstyle.org/google_style.html).
+You can also use a custom ruleset in the plugin configuration.
 
 Goals Overview
 --------------
@@ -39,34 +44,48 @@ The Checkstyle Plugin has three goals:
 
 - [checkstyle:checkstyle](./checkstyle-mojo.html) is a reporting goal that 
performs Checkstyle analysis and generates a report on violations.
 - [checkstyle:checkstyle-aggregate](./checkstyle-aggregate-mojo.html) is a 
reporting goal that performs Checkstyle analysis and generates an aggregate 
HTML report on violations in a multi-module reactor build.
-- [checkstyle:check](./check-mojo.html) is a goal that performs Checkstyle 
analysis and outputs violations or a count of violations to the console, 
potentially failing the build. It can also be configured to re-use an earlier 
analysis.
+- [checkstyle:check](./check-mojo.html) is a goal that performs Checkstyle 
analysis and outputs violations or a count of violations to the console.
+  It can also fail the build.
+  You can configure it to re-use an earlier analysis.
 
 Major Version Upgrade to version 3.0.0
 --------------------------------------
 
-Please note that the following parameters have been completely removed from 
the plugin configuration:
+These two parameters were removed from the plugin configuration:
 
-- `sourceDirectory`: use `sourceDirectories` instead;
+- `sourceDirectory`: use `sourceDirectories` instead.
 - `testSourceDirectory`: use `testSourceDirectories` instead.
 
 Usage
 -----
 
-General instructions on how to use the Checkstyle Plugin can be found on the 
[usage page](./usage.html). Some more specific use cases are described in the 
examples given below.
+General instructions on how to use the Checkstyle Plugin are on the [usage 
page](./usage.html).
+The examples below describe more specific use cases.
 
-In case you still have questions regarding the plugin's usage, please have a 
look at the [FAQ](./faq.html) and feel free to contact the [user mailing 
list](./mailing-lists.html). The posts to the mailing list are archived and 
could already contain the answer to your question as part of an older thread. 
Hence, it is also worth browsing/searching the [mail 
archive](./mailing-lists.html).
+If you still have questions about the plugin's usage, look at the 
[FAQ](./faq.html).
+You can also contact the [user mailing list](./mailing-lists.html).
+The posts to the mailing list are archived.
+An older thread can contain the answer to your question.
+You can also search the [mail archive](./mailing-lists.html).
 
-If you feel like the plugin is missing a feature or has a defect, you can fill 
a feature request or bug report in our [issue 
tracker](https://issues.apache.org/jira/projects/MCHECKSTYLE/). When creating a 
new issue, please provide a comprehensive description of your concern. 
Especially for fixing bugs it is crucial that the developers can reproduce your 
problem. For this reason, entire debug logs, POMs or most preferably little 
demo projects attached to the issue are very much appreciate [...]
+If you think that the plugin lacks a feature or has a defect, report it in the 
[issue tracker](https://issues.apache.org/jira/projects/MCHECKSTYLE/).
+When you create a new issue, include a comprehensive description of your 
concern.
+For bug fixes, the developers must be able to reproduce your problem.
+Attach entire debug logs, POMs, or little demo projects to the issue.
+Patches are welcome.
+
+Contributors can check out the project from the [source 
repository](./scm.html).
+They can also find supplementary information in the [guide to helping with 
Maven](https://maven.apache.org/guides/development/guide-helping.html).
 
 Examples
 --------
 
-The following examples show how to use the Checkstyle Plugin in more advanced 
usecases:
+The examples below show how to use the Checkstyle Plugin in more advanced use 
cases:
 
-- [Upgrading Checkstyle at Runtime](./examples/upgrading-checkstyle.html)
-- [Using an 'Inline' Checkstyle Checker 
Configuration](./examples/inline-checker-config.html)
-- [Using a Custom Checkstyle Checker 
Configuration](./examples/custom-checker-config.html)
-- [Using Custom Checkstyle Property Expansion 
Definitions](./examples/custom-property-expansion.html)
-- [Using a Suppressions Filter](./examples/suppressions-filter.html)
-- [Using Custom Developed Checkstyle Check 
Modules](./examples/custom-developed-checkstyle.html)
+- [Upgrade Checkstyle at Runtime](./examples/upgrading-checkstyle.html)
+- [Inline Checkstyle Checker 
Configuration](./examples/inline-checker-config.html)
+- [Custom Checkstyle Checker 
Configuration](./examples/custom-checker-config.html)
+- [Custom Checkstyle Property Expansion 
Definitions](./examples/custom-property-expansion.html)
+- [Suppressions Filter](./examples/suppressions-filter.html)
+- [Custom Developed Checkstyle Check 
Modules](./examples/custom-developed-checkstyle.html)
 - [Multimodule Configuration](./examples/multi-module-config.html)
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 567c24b..7af9f9c 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -26,12 +26,13 @@ under the License.
 
 # Usage
 
-The following examples describe the basic usage of the Checkstyle Plugin.
+The examples below describe the basic usage of the Checkstyle Plugin.
 
 Generate Checkstyle Report As Part of the Project Reports
 ---------------------------------------------------------
 
-To generate the Checkstyle report as part of the Project Reports, add the 
Checkstyle Plugin in the `<reporting>` section of your `pom.xml`.
+Generate the Checkstyle report as part of the Project Reports.
+Add the Checkstyle Plugin to the `<reporting>` section of your `pom.xml`.
 
 ```xml
 <project>
@@ -56,7 +57,7 @@ To generate the Checkstyle report as part of the Project 
Reports, add the Checks
 </project>
 ```
 
-Then, execute the site phase to generate the report.
+Run the site phase to generate the report.
 
 ```shell
 mvn site
@@ -65,20 +66,32 @@ mvn site
 Generate Checkstyle Report As Standalone
 ----------------------------------------
 
-You can also generate the Checkstyle report by explicitly executing the 
`checkstyle:checkstyle` goal from the command line. You are not required to 
specify the Checkstyle Plugin in your `pom.xml` unless you want to use a 
specific configuration.
+You can also generate the Checkstyle report with the `checkstyle:checkstyle` 
goal from the command line.
+You do not need to specify the Checkstyle Plugin in your `pom.xml` unless you 
need a specific configuration.
 
 ```shell
 mvn checkstyle:checkstyle
 ```
 
-Checking for Violations as Part of the Build
---------------------------------------------
+Check for Violations as Part of the Build
+-----------------------------------------
 
-If you want to report to the console or fail the build, you must add an 
execution of `checkstyle::check` to the `<build>` element and configure any 
options that you need.
+If you want the console report or a build failure, add an execution of 
`checkstyle::check` to the `<build>` element.
+Configure any options that you need.
 
-Options you set in the `<reporting>` element do not have any effect on 
executions in the `<build>` element.
+Options that you set in the `<reporting>` element do not affect executions in 
the `<build>` element.
 
-Note that the phase that `checkstyle::check` is bound to is very important. If 
bound to the validate phase, it would check the code prior to compiling the 
code. If the code is invalid, the parsing errors reported by checkstyle may be 
different than what would be expected from the javac compiler. However, it's 
guaranteed to run. Another popular option is to bind it to the verify phase 
which would run much later (and allow the javac compiler to flag invalid code 
prior to checkstyle). Howev [...]
+The phase that `checkstyle::check` is bound to is important.
+If you bind it to the validate phase, it checks the code before compilation.
+It is guaranteed to run.
+If the code is invalid, the errors that checkstyle reports can differ from the 
errors from the javac compiler.
+
+Another common option binds the goal to the verify phase.
+The verify phase runs much later than the validate phase.
+A later phase lets the javac compiler flag invalid code before checkstyle runs.
+
+If developers run `mvn test` before they push changes, checkstyle does not run.
+The verify phase occurs after the test phase.
 
 For example:
 
diff --git a/src/site/site.xml b/src/site/site.xml
index fd37ffd..e66a943 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -32,12 +32,12 @@ under the License.
       <item name="Releases History" href="history.html"/>
     </menu>
     <menu name="Examples">
-      <item name="Upgrading Checkstyle at Runtime" 
href="/examples/upgrading-checkstyle.html"/>
-      <item name="Using an Inline Checkstyle Checker Configuration" 
href="/examples/inline-checker-config.html"/>
-      <item name="Using a Custom Checkstyle Checker Configuration" 
href="/examples/custom-checker-config.html"/>
-      <item name="Using Custom Checkstyle Property Expansion Definitions" 
href="/examples/custom-property-expansion.html"/>
-      <item name="Using a Suppressions Filter" 
href="/examples/suppressions-filter.html"/>
-      <item name="Using Custom Developed Checkstyle Checks" 
href="/examples/custom-developed-checkstyle.html"/>
+      <item name="Upgrade Checkstyle at Runtime" 
href="/examples/upgrading-checkstyle.html"/>
+      <item name="Inline Checkstyle Checker Configuration" 
href="/examples/inline-checker-config.html"/>
+      <item name="Custom Checkstyle Checker Configuration" 
href="/examples/custom-checker-config.html"/>
+      <item name="Custom Checkstyle Property Expansion Definitions" 
href="/examples/custom-property-expansion.html"/>
+      <item name="Suppressions Filter" 
href="/examples/suppressions-filter.html"/>
+      <item name="Custom Developed Checkstyle Checks" 
href="/examples/custom-developed-checkstyle.html"/>
       <item name="Multimodule Configuration" 
href="/examples/multi-module-config.html"/>
     </menu>
   </body>

Reply via email to