Merge branch 'stable-2.11' into master

Change-Id: I0e2c67b34696e43c07ff97a8444c43f1fb35042e
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
index 84d3eb1..389b896 100644
--- a/src/main/resources/Documentation/about.md
+++ b/src/main/resources/Documentation/about.md
@@ -1,12 +1,12 @@
-This @PLUGIN@ plugin is an [`its-base`][its-base] based plugin that integrates
-Gerrit and [`Storyboard`][storyboard].  The @PLUGIN@ allows users
-to configure how a storyboard story or task should be updated relative
-to Gerrit change updates.  For example, it can be configured to
-automatically add comments to a story when a comment is entered to
-an associated Gerrit change.  It can also be configured to update a
-story's status upon an update to an associated Gerrit change.
+This @PLUGIN@ plugin is an [`its-base`][its-base] based plugin that
+integrates Gerrit and [`Storyboard`][storyboard].  The @PLUGIN@ plugin
+allows users to configure how a storyboard story and task should be
+updated relative to Gerrit change updates.  For example, it can be
+configured to automatically add comments to a story when a comment is
+entered to an associated Gerrit change.  It can also be configured to
+update status on a task when an associated Gerrit change is updated.
 
-For details on how to install this plugin start with the
+For details on how to install and configure this plugin start with the
 [Quick Install Guide][quick].
 
 [quick]: quick-install-guide.md
diff --git a/src/main/resources/Documentation/quick-install-guide.md b/src/main/resources/Documentation/quick-install-guide.md
index 8f2e1c4..97327b6 100644
--- a/src/main/resources/Documentation/quick-install-guide.md
+++ b/src/main/resources/Documentation/quick-install-guide.md
@@ -2,18 +2,19 @@
 ===================
 
 For general instructions on how to enable and configure an its plugin
-please refer to the general [configuration documentation][config-doc]
+please refer to the general [configuration documentation][config-doc].
 Instructions in this document are specific to the @PLUGIN@ plugin.
 
 Install Steps:
 
-1. Verify Storyboard [REST endpoint][rest-enabled].
-2. [Configure the connection][its-connection].
-3. [Associate a changes with stories][its-associate-change].
-4. [Configure the actions][its-actions] that the plugin will take on a Gerrit change.
-5. [Enable the @PLUGIN@ plugin][its-enable] for the Gerrit project.
+1. [Check Storyboard REST API availability][rest-enabled]
+2. [Connection Configuration][its-connection].
+3. [Verify access to Storyboard][access-enabled]
+4. [Associate Gerrit changes with Storyboard stories and tasks][its-associate-change].
+5. [Configure the actions][its-actions] that the plugin will take on a Gerrit change update.
 6. [Install the plugin][its-install]
-7. Restart Gerrit
+7. [Enable the @PLUGIN@ plugin][its-enable] for the Gerrit project.
+8. [Testing][testing]
 
 [rest-enabled]: #rest-enabled
 <a name="rest-enabled">Checking REST API availability</a>
@@ -38,9 +39,9 @@
 <a name="its-connection">Connection Configuration</a>
 -----------------------------------------------------
 
-In order for @PLUGIN@ to connect to the REST service of your
+In order for the @PLUGIN@ plugin to connect to the REST service of your
 Storyboard instance, the url and credentials are required in
-your site's `etc/gerrit.config` or `etc/secure.config` under
+your Gerrit site's `etc/gerrit.config` or `etc/secure.config` under
 the `@PLUGIN@` section.
 
 Example:
@@ -51,27 +52,44 @@
   password=STORYBOARD_USER_AUTH_TOKEN
 ```
 
+[access-enabled]: #access-enabled
+<a name="access-enabled">Check Accessibility</a>
+---------------------------------------------------------
+
+This plugin uses the Storyboard REST endpoints to POST updates.  Make sure
+that the STORYBOARD_USER_AUTH_TOKEN has access to update Storyboard stories
+and tasks. To verify this use the [Storyboard story API] from the Gerrit sever
+to post an update. If it fails to update the story you'll need to make the
+necessary changes to allow access between the Gerrit and Storyboard
+servers.
+
+
 [its-associate-change]: #its-associate-change
 <a name="its-associate-change">Associating Gerrit Changes</a>
 -------------------------------------------------------------
 
-In order for @PLUGIN@ to associate a Gerrit change with
-a Storyboard story, a Gerrit commentlink needs to be
+In order for the @PLUGIN@ plugin to associate a Gerrit change with
+a Storyboard story and task, a Gerrit commentlink needs to be
 defined in `etc/gerrit.config`
 
 Example:
 
 ```
+[commentlink "story"]
+    match = "\\b[Ss]tory:? #?(\\d+)"
+    link = "http://my_storyboard_instance.com/#!/story/$1"
+    html = ""
 [commentLink "@PLUGIN@"]
-  match = [Ss][Tt][Oo][Rr][Yy][ ]*([1-9][0-9]*)
-  html = "<a href=\"https://my_storyboard_instance.com/#!/story/$1\">story $1</a>"
+    match = "\\b[Tt]ask:? #?(\\d+)"
+    link = "task: $1"
+    html = ""
 ```
 
 [its-actions]: #its-actions
 <a name="its-actions">Configure its actions</a>
 -----------------------------------------------
 
-The @PLUGIN@ plugin can take action when there are updates
+The @PLUGIN@ plugin can take actions when there are updates
 to Gerrit changes.  Users can define what events will trigger
 which actions.  To configure this a `etc/its/actions.config`
 file is required.
@@ -83,24 +101,34 @@
 [rule "update-comment"]
     event-type = comment-added
     action = add-velocity-comment inline $commenter-name commented on change ${its.formatLink($change-url, $subject)}
+
 # add a comment only when a user leaves a -2 or a -1 vote on the Code-Review label on the associated Gerrit change.
 [rule "comment-on-negative-vote"]
     event-type = comment-added
     approval-Code-Review = -2,-1
     action = add-comment Boo-hoo, go away!
+
 # add a standard comment when there is a status update to the associated Gerrit change.
 [rule "comment-on-status-update"]
     event-type = patchset-created,change-abandoned,change-restored,change-merged
     action = add-standard-comment
-# set task status to 'review' when a patch is uploaded or when a change is restored
-[rule "change_restored"]
+
+# set storyboard task status to 'review' when a patch is uploaded or when a change is restored
+[rule "change-in-progress"]
     event-type = patchset-created,change-restored
     action = set-status REVIEW
 ```
+*_NOTE_: A Gerrit restart is required to update these settings.
 
 ### <a id="task-status"></a>TaskStatus
 Valid task status: TODO, REVIEW, INPROGRESS, MERGED, and INVALID
 
+[its-install]: #its-install
+<a name="its-install">Install the Plugin</a>
+-------------------------------------------------------
+
+In order to install the @PLUGIN@ plugin simply copy the built jar
+file into the `plugins` folder.
 
 [its-enable]: #its-enable
 <a name="its-enable">Enable the Plugin</a>
@@ -118,18 +146,31 @@
   enabled = true
 ```
 
-[its-install]: #its-install
-<a name="its-install">Install the Plugin</a>
+[testing]: #testing
+<a name="testing">Testing the Plugin</a>
 -------------------------------------------------------
 
-In order to install the @PLUGIN@ plugin simply copy the built jar
-file into the `plugins` folder.
+Create a new Gerrit change with a commit message that contains a reference
+to the Storyboard story and task.
 
-[config-common-doc]: config-common.md
-[config-doc]: config.md
-[rules-doc]: config-rulebase-common.md
+Example:
 
+```
+My change to test integration
+
+This is an example change to test storyboard integration.
+Story: 123
+Task: 1000
+Change-Id: I3912f42c371023eb8bd048a5b17b776801b405e2
+```
+
+Make an update to the Gerrit change (abandone, restore, submit, etc..),
+the @PLUGIN@ plugin should automatically update the corresponding story
+and task in Storyboard.
 
 SEE ALSO
 --------
-* More detailed information on actions is found the [rules documentation][rules-doc]
+* More detailed information on actions is found in the [rules documentation][rules-doc]
+
+
+[Storyboard story API]: http://docs.openstack.org/infra/storyboard/webapi/v1.html#put--v1-stories