Updated documentation guide
Change-Id: I0b629d79d4bebfd8f86da79149e1396a299ba119
diff --git a/readme.rst b/documentation.rst
similarity index 60%
rename from readme.rst
rename to documentation.rst
index 6863626..c067956 100644
--- a/readme.rst
+++ b/documentation.rst
@@ -1,24 +1,29 @@
Documentation Guide
-===================
+*******************
-Building the Docs
-------------------
+Overview
+========
-The documentation build process is stored in the Makefile. Building docs
-requires Python to be installed, and most steps will create a virtualenv
-(``doc_venv``) which install the documentation generation toolset.
+Trellis documentation is hosted on `Gerrit <https://gerrit.onosproject.org/admin/projects/trellis-docs>`_ and published automatically to https://docs.trellisfabric.org whenever there is a patch being merged.
+Here we're going to explain how to make modifications to this documentation.
-Run ``make html`` to generate html documentation in ``_build/html``.
+.. tip::
+ The review workflow is almost identical to ONOS.
+ Please check `Sample Gerrit Workflow <https://wiki.onosproject.org/display/ONOS/Sample+Gerrit+Workflow>`_ if you are not yet familiar with the review workflow.
-Run ``make reload`` to get a live reload in your browser (refreshes on document
-save).
-To check the formatting of documentation, run ``make lint``. This will be done
-in Jenkins to validate the documentation, so please do this before you create a
-patchset.
+Downloading Docs
+================
+
+.. code-block:: console
+
+ $ git clone ssh://<username>@gerrit.onosproject.org:29418/trellis-docs
+
+``<username>`` should be replaced with your Gerrit username.
+
Writing Docs
-------------
+============
Docs are generated using Sphinx: http://www.sphinx-doc.org
@@ -49,3 +54,33 @@
- blockdiag: http://blockdiag.com/en/blockdiag/examples.html
- nwdiag: http://blockdiag.com/en/nwdiag/nwdiag-examples.html
- rackdiag: http://blockdiag.com/en/nwdiag/rackdiag-examples.html
+
+
+Building Docs
+=============
+
+The documentation build process is stored in the Makefile. Building docs
+requires Python to be installed, and most steps will create a virtualenv
+(``doc_venv``) which install the documentation generation toolset.
+
+Run ``make html`` to generate html documentation in ``_build/html``.
+
+Run ``make reload`` to get a live reload in your browser (refreshes on document
+save).
+
+To check the formatting of documentation, run ``make test``. This will be done
+in Jenkins to validate the documentation, so please do this before you create a
+patchset.
+
+
+Submitting a Review
+===================
+
+**Make sure you build and test the changes**.
+Once done, you can submit a review by running the following commands:
+
+.. code-block:: console
+
+ $ git add .
+ $ git commit -m '<commit message>'
+ $ git review
diff --git a/index.rst b/index.rst
index 2c669ab..8bcf3a3 100644
--- a/index.rst
+++ b/index.rst
@@ -94,4 +94,4 @@
troubleshooting
development
testing
- readme
+ documentation