doc: update the documentation
Update the docs with better description and add a reference to
the Jenkins verify-status-reporter plugin.
Change-Id: I23286ae1bf8467fe7f4807839542feba38113309
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
index 55f030a..fb16e7f 100644
--- a/src/main/resources/Documentation/about.md
+++ b/src/main/resources/Documentation/about.md
@@ -1,25 +1,55 @@
-The @PLUGIN@ plugin allows CI system to report build and test results back to
-Gerrit. The reports are stored per patchset and are saved onto an external
-database. Included with this plugin are a set of SSH and REST APIs to automate
-the reporting of test results. This plugin will also handle displaying of the
-job results on the Gerrit UI.
+The @PLUGIN@ plugin seperates test results from comments. It provides a
+separate channel for Gerrit to store test metadata and view them on the
+Gerrit UI. The metadata can be stored in the Gerrit database or in a
+completely separate datastore.
+Typically a CI system, like [Jenkins], will post test metadata to Gerrit as a
+comment. It looks something like this..
+
+```
+Jenkins Aug 24 3:57 PM
+Patch Set 5: Verified-1
+Build Failed
+http://jenkins.acme.com/job/python-27-wacko/4/ : FAILURE
+http://jenkins.acme.com/job/python-27-pep8/6/ : SUCCESS
+http://jenkins.acme.com/job/python-27/4/ : SUCCESS
+..
+```
+
+The problem occurs when there are many jobs verifying each patchset. An
+increased number of reports from Jenkins can overwhelm reviewers who must look
+through the comments and decipher which replies to pay attention to. After a
+while the CI reports become more like spam. Usually human reviewers only
+want to view comments that have been posted by other humans reviewers not bots.
+Since humans and bots must share a communications (or comments) channel it's
+difficult to separate the two competing pieces of data for the purposes of
+reviewing, visualizations and even analytics.
+
+This is where the @PLUGIN@ plugin comes in. It creates a separate channel for
+bots to report info to Gerrit. It provides a separate database to store the
+info and it provides a set of SSH commands and REST endpoints to save
+and retrieve the data. It also provides UI components to view the data
+outside of the Gerrit comments.
### <a id="workflow"></a>
### `Workflow`
-A typical workflow for @PLUGIN@ plugin:
+Any CI system can be used with the @PLUGIN@ plugin.
+A typical workflow:
1. CI system triggers on a new patchset.
2. CI system executes build jobs.
-3. CI system reports build job results with @PLUGIN@ [ssh command](cmd-save.md)
-or [rest-api](rest-api-changes.md).
+3. CI system reports build job results with the @PLUGIN@
+[ssh command](cmd-save.md) or [rest-api](rest-api-changes.md).
4. CI system reports a combined `Verfiied` vote based on the results of each job
using the review [ssh command](../../../Documentation/cmd-review.html) or
-[rest-api](../../../Documentation/rest-api-changes.html#set-review).
+[rest api](../../../Documentation/rest-api-changes.html#set-review).
5. Users can view per patch job results on Gerrit UI or retrieve the results
using the @PLUGIN@ rest api.
+_NOTE_: The [verify-status-reporter] plugin documentation contains specific
+instructions on setting up this workflow with the Jenkins CI system.
+
### <a id="change-screen"></a>
### `Change Screen`
@@ -74,3 +104,6 @@
showJobsDropDownPanel = false
```
+
+[Jenkins]: https://jenkins.io
+[verify-status-reporter]: https://wiki.jenkins-ci.org/display/JENKINS/Verify+Status+Reporter
diff --git a/src/main/resources/Documentation/database.md b/src/main/resources/Documentation/database.md
index cdea76d..852e54f 100644
--- a/src/main/resources/Documentation/database.md
+++ b/src/main/resources/Documentation/database.md
@@ -3,20 +3,20 @@
DESCRIPTION
-----------
-CI data is stored in a [CI database](#supported-dbs) which can be in the Gerrit
-review database or a completely separate database.
+Test metadata is stored in a [CI database](#supported-dbs) which can be in the
+Gerrit review database or a completely separate database.
### <a id="schema-initialization"> @PLUGIN@ schema initialization
Schema initialization
---------------------
-The database is initialized and the schema is created with during an initial
+The database is initialized and the schema is created during an initial
site creation.
```
*** SQL Database for @PLUGIN@
-***
+***
Database server type [h2]: ?
Supported options are:
@@ -35,13 +35,13 @@
Schema upgrade
--------------
-Schema upgrade takes place in init plugin step:
+Schema upgrade takes place in the init plugin step:
```
*** SQL Database for @PLUGIN@
-***
+***
-Database server type [h2]:
+Database server type [h2]:
Upgrading schema to 2 ...
Migrating data to schema 2 ...
@@ -56,8 +56,8 @@
(../../../Documentation/config-gerrit.html#_file_code_etc_gerrit_config_code)
file
-The [database section](#database-params) configures where the @PLUGIN@ stores
-per patchset CI results.
+The [database section](#database-params) configures where the @PLUGIN@ plugin
+stores per patchset test results.
```
[plugin "@PLUGIN@"]
@@ -105,7 +105,7 @@
Acccesing Database
------------------
-@PLUGIN@ provides an administrative interface to the database.
+@PLUGIN@ plugin provides an administrative interface to the database.
'ssh' -p <port> <host> '@PLUGIN@ gsql' [--format {PRETTY | JSON | JSON_SINGLE}] [-c QUERY]
