Updated documentation guide
Change-Id: I0b629d79d4bebfd8f86da79149e1396a299ba119
diff --git a/documentation.rst b/documentation.rst
new file mode 100644
index 0000000..c067956
--- /dev/null
+++ b/documentation.rst
@@ -0,0 +1,86 @@
+Documentation Guide
+*******************
+
+Overview
+========
+
+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.
+
+.. 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.
+
+
+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
+
+Documentation is done in `reStructuredText
+<http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`__
+(``.rst``) or the `CommonMark flavor of Markdown
+<https://spec.commonmark.org/>`__ (``.md``), but only .rst files can use certain
+features like embedded diagrams or tables.
+
+One tool that is useful for converting between text formats is `Pandoc
+<https://pandoc.org>`__ - for example, to convert a ``.html`` file to ``.rst``,
+you can run ``pandoc file.html -o file.rst``.
+
+Creating Diagrams
+-----------------
+
+The blockdiag suite of tools can be used for inline diagramming in ``.rst``
+files:
+
+- Block diagrams: http://blockdiag.com/en/blockdiag/sphinxcontrib.html
+- Network diagrams (& racks): http://blockdiag.com/en/nwdiag/sphinxcontrib.html
+
+Attributes that can be applied to nodes:
+http://blockdiag.com/en/blockdiag/attributes/node.attributes.html
+
+Examples:
+
+- 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