Update documentation (#779)

README.md

@@ -5,34 +5,18 @@
 
 ## Introduction
 
-This new parent POM is decoupled from the core Jenkins project, both from the Maven and repository perspectives.
-
-Since version 4.52 the plugin parent POM supports Jenkins 2.361 and higher.
-
-The main changes are:
-* Reduced number of overridable properties. All references (e.g. dependencies and plugin versions) not
-thought to be overridden are no longer based on properties. The main remaining overridable properties are:
-  * `jenkins.version`: The Jenkins version required by the plugin. **Mandatory.**
-     See [Java Support](#java-support) for more info.
-  * `jenkins-test-harness.version`: The [JTH version](https://github.com/jenkinsci/jenkins-test-harness/releases) used to test plugin.
-  Uses split test-harness (see [JENKINS-32478](https://issues.jenkins-ci.org/browse/JENKINS-32478)).
-  * `hpi-plugin.version`: The HPI Maven Plugin version used by the plugin.
-  (Generally you should not set this to a version _lower_ than that specified in the parent POM.)
-  * `stapler-plugin.version`: The Stapler Maven plugin version required by the plugin.
-  * In order to make their versions the same as the used core version, `node.version` and `npm.version`
-  properties are provided.
-* Tests are skipped during the `perform` phase of a release (can be overridden by setting `release.skipTests` to false).
-* Javadoc has been set to _quiet_ by default in 2.20+, which means it will only log errors and warnings. 
-  If you really want it verbose, set `quiet` property to `false` for the plugin.
-* General clean up.
-
-Being able to specify the `jenkins.version` simplifies testing the plugin with different core versions, which is
-important, among others, for the Plugin Compatibility Testing.
+The plugin parent POM is decoupled from the core Jenkins project, both from a Maven perspective and a repository perspective.
+It provides a common build configuration for all Jenkins plugins.
+
+## Requirements
+
+Since version 4.52, the plugin parent POM requires Jenkins 2.361 or newer and JDK 11 or newer.
+Since version 4.40, the plugin parent POM supports Java 17.
 
 ## Usage
 
-In order to use the new POM:
-* Change the parent POM of your plugin:
+To use the plugin parent POM, change the parent POM of your plugin:
+
 ```xml
   <parent>
     <groupId>org.jenkins-ci.plugins</groupId>
@@ -41,7 +25,9 @@ In order to use the new POM:
     <relativePath />
   </parent>
 ```
-* Override the needed properties, e.g.:
+
+Then override the needed properties, e.g.:
+
 ```xml
   <properties>
     <!--
@@ -52,16 +38,21 @@ In order to use the new POM:
   </properties>
 ```
 
-If you had a `jar:test-jar` execution, delete it and add to `properties`:
+If you have a `jar:test-jar` execution, delete it and add the following to `<properties>`:
 
 ```xml
 <no-test-jar>false</no-test-jar>
 ```
 
-## Java support
+## Overridable properties
+
+The following properties are overridable:
 
-The plugin POM is designed for plugin builds with JDK 11 or above.
-Starting from Plugin POM `4.40`, support of Java 17 was added.
+* `jenkins.version`: The Jenkins version required by the plugin. **Mandatory.** See [Requirements](#requirements) for more info. Being able to specify the `jenkins.version` simplifies testing the plugin with different core versions, which is important (among other reasons) for Plugin Compatibility Testing (PCT).
+* `jenkins-test-harness.version`: The [JTH version](https://github.com/jenkinsci/jenkins-test-harness/releases) used to test plugin. Uses split test-harness (see [JENKINS-32478](https://issues.jenkins-ci.org/browse/JENKINS-32478)).
+* `hpi-plugin.version`: The HPI Maven Plugin version used by the plugin. (Generally you should not set this to a version _lower_ than that specified in the plugin parent POM.)
+* `stapler-plugin.version`: The Stapler Maven plugin version required by the plugin.
+* In order to make their versions the same as the used core version, `node.version` and `npm.version` properties are provided.
 
 ## Incrementals
 
@@ -98,11 +89,22 @@ be detected when using `-Dbenchmark`, however, `FooBar` will be ignored.
 
 See also: [documentation for JMH benchmarks](https://github.com/jenkinsci/jenkins-test-harness/blob/master/docs/jmh-benchmarks.adoc)
 
+## Javadoc
+
+Javadoc has been set to _quiet_ by default in 2.20+, which means it will only log errors and warnings.
+If you really want it verbose, set `quiet` property to `false` for the plugin.
+
+## Releasing
+
+Tests are skipped during the `perform` phase of a release. This can be overridden by setting `release.skipTests` to false.
+
 ## Setup Wizard
 
 By default, the setup wizard (Jenkins >= 2.0) is skipped when using `hpi:run`. If you want the wizard to be enabled just run:
 
-    mvn -Dhudson.Main.development=false hpi:run
+```bash
+mvn -Dhudson.Main.development=false hpi:run
+```
 
 ## Jenkins Core BOM