Update docs
update docs
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f884c9f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,20 @@
+# Gerrit Depends On Plugin
+
+Openstack uses [Zuul] for project gating and one of the features of Zuul is
+[cross repository dependencies] (CRD). Zuul will detect CRDs in git
+commit messages to allow it to arrange patchsets (in order) before scheduling
+them for build and test.
+
+It can become very difficult, downright confusing really to determine the
+dependency relationships with only the 'depends-on' reference. Also the use
+of CRD can produce [dependency cycles] which can cause Zuul to be ineffective.
+To help alleviate these issues this plugin adds a 'needed-by' reference on the
+Gerrit UI. It also adds dependency cycle detection and will display the CRD
+references in red if a cycle has been detected. This plugin also adds a REST
+endpoint to allow other clients to retrieve CRD info.
+
+More information about this plugin can be found in the documentation.
+
+[Zuul]: http://docs.openstack.org/infra/zuul/index.html
+[cross repository dependencies]: http://docs.openstack.org/infra/zuul/gating.html#cross-repository-dependencies
+[dependency cycles]: http://docs.openstack.org/infra/zuul/gating.html#cycles
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
index 30063b0..e52e83f 100644
--- a/src/main/resources/Documentation/about.md
+++ b/src/main/resources/Documentation/about.md
@@ -1,5 +1,7 @@
-The @PLUGIN@ plugin displays Zuul cross repository dependencies (CRD)
-info on the Gerrit UI.
+The @PLUGIN@ plugin detects Zuul [cross repository dependencies] (CRD) in
+commit messages and displays it on the Gerrit UI. [Cycles] are shown in red
![ZuulCRDScreenshot](images/zuul_crd.png)
+[cross repository dependencies]: http://docs.openstack.org/infra/zuul/gating.html#cross-repository-dependencies
+[Cycles]: http://docs.openstack.org/infra/zuul/gating.html#cycles
diff --git a/src/main/resources/Documentation/rest-api-changes.md b/src/main/resources/Documentation/rest-api-changes.md
index c35fa3a..b754ac1 100644
--- a/src/main/resources/Documentation/rest-api-changes.md
+++ b/src/main/resources/Documentation/rest-api-changes.md
@@ -54,7 +54,7 @@
|Field Name |Description|
|:----------|:----------|
|depends_on |List of changes that this change depends on|
-|needed-by |List of changes that is dependent on this change|
+|needed_by |List of changes that is dependent on this change|
|cycle |Whether this change is in a circular dependency chain|