Documentation cleanup

Change-Id: Ifd749c80cbf5569bbc7c609a88107db207ed5b9f
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md
index d76fe05..2cca3f4 100644
--- a/src/main/resources/Documentation/config.md
+++ b/src/main/resources/Documentation/config.md
@@ -1,14 +1,14 @@
 Plugin @PLUGIN@
 ===============
 
-This plugin allows to associate Jira issues to Git commits thanks to
-the Gerrit listener interface.
+This plugin allows to associate Jira issues to Git commits.
 
 Comment links
 ----------------
 
 Git commits are associated to Jira issues reusing the existing Gerrit
-[commitLink configuration][1] to extract the issue ID from commit comments.
+[commitLink configuration][1] to extract the issue-id from the commit
+messages.
 
 [1]: ../../../Documentation/config-gerrit.html#__a_id_commentlink_a_section_commentlink
 
@@ -20,11 +20,11 @@
 	 the git push will be rejected.
 
 SUGGESTED
-:	 Whenever git commit message does not contain one or more issue-ids,
+:	 Whenever a git commit message does not contain any issue-id,
 	 a warning message is displayed as a suggestion on the client.
 
 OPTIONAL
-:	 Issues-ids are linked when found on git commit message, no warnings are
+:	 Issue-ids are linked when found in a git commit message. No warning is
 	 displayed otherwise.
 
 Example:
@@ -35,14 +35,15 @@
     association = SUGGESTED
 
 Once a Git commit with a comment link is detected, the Jira issue ID
-is extracted and a new comment added to the issue, pointing back to
+is extracted and a new comment is added to the issue, pointing back to
 the original Git commit.
 
 Jira connectivity
 -----------------
 
-In order for Gerrit to connect to Jira/SOAP-API url and credentials
-are required in your gerrit.config / secure.config under the [jira] section.
+In order for Gerrit to connect to Jira/SOAP-API URL and credentials
+are required in your `gerrit.config` / `secure.config` under the
+`[jira]` section.
 
 Example:
 
@@ -57,7 +58,7 @@
 ---------------------
 
 It is possible to choose which kind of Gerrit event will trigger the plugin to comment on
-the Jira issue by adding the following in your gerrit.config file under the [jira] section:
+the Jira issue by adding the following in your `gerrit.config` file under the `[jira]` section:
 
 commentOnChangeAbandoned
 :	If true, abandoning a change adds a comment to the issue.
@@ -84,7 +85,7 @@
 commentOnRefUpdatedGitWeb
 :	If true, updating a ref adds a comment to the issue.
 
-By default they are set to true
+By default all parameters are set to true.
 
 Example:
 
@@ -95,9 +96,9 @@
 Gerrit init integration
 -----------------------
 
-Jira plugin is integrated as a Gerrit init step in order to simplify and guide
-through the configuration of Jira integration and connectivity check, avoiding
-bogus settings to prevent Gerrit plugin to start correctly.
+The Jira plugin comes with a Gerrit init step that simplifies the
+initial configuration. It guides through the configuration of the Jira
+integration and checks the connectivity.
 
 Gerrit init example:
 
@@ -141,24 +142,25 @@
 Syntax of the status transition configuration file is the following:
 
     [action "<issue-status-action>"]
-    change=<change-action>
+    change=<state-change-type>
     verified=<verified-value>
     code-review=<code-review-value>
 
 `<issue-status-action>`
-:	Action to perform on Jira issue when all the condition in the stanza are met.
+:	Action to be performed on the Jira issue when all the condition in the stanza are met.
 
-`<change-action>`
-:	Action performed on Gerrit change-id, possible values are:
-	`created, commented, merged, abandoned, restored`
+`<state-change-type>`
+:	Gerrit state change type on which the action will be triggered.
+	Possible values are: `created`, `commented`, `merged`, `abandoned`,
+	`restored`
 
 `<verified-value>`
-:	Verified flag added on Gerrit with values from -1 to +1
+:	Verified label added on the Gerrit change with a value from -1 to +1
 
 `<code-review-value>`
-:	Code-Review flag added on Gerrit with values from -2 to +2
+:	Code-Review label added on the Gerrit change with a value from -2 to +2
 
-Note: multiple conditions in the action stanza are optional but at least one must be present.
+Note: multiple conditions in the action stanza are possible but at least one must be present.
 
 Example:
 
@@ -175,9 +177,9 @@
     [action "Stop Progress"]
     change=abandoned
 
-The above example defines four status transition on Jira, based on the following conditions:
+The above example defines four status transitions on Jira, based on the following conditions:
 
-* Whenever a new Change-set is created on Gerrit, start progress on the Jira issue
-* Whenever a change is verified and reviewed with +2, transition the Jira issue to resolved
-* Whenever a change is merged to branch, mark the Jira transition the Jira issue to closed
-* Whenever a change is abandoned, stop the progress on Jira issue
+* Whenever a new Change is created on Gerrit, start progress on the Jira issue
+* Whenever a change is verified and reviewed with +2, set the Jira issue to resolved
+* Whenever a change is merged to the branch, close the Jira issue
+* Whenever a change is abandoned, stop the progress on the Jira issue