Improve documentation README

doc/README

@@ -1,4 +1,4 @@
-How to build documentation
+Overview
 --------------------------
 
 The VTR documentaion is generated using sphinx, a python based documenation generator.
@@ -8,31 +8,53 @@ is a lightwieght mark-up language for text documents.
 
 Currently VTR's documenation is automatically built by www.readthedocs.org and is served at:
 
-    https://vtr.readthedocs.org/en/latest/
+    https://vtr.readthedocs.io/
+
+
+How to build documentation
+--------------------------
+
+To build the documentation locally you need sphinx installed:
+
+    For ubuntu/debian based systems:
 
-To build the documentation locally you need sphinx installed.
+        $ apt-get install python-sphinx
 
-For ubuntu/debian based systems:
+    To properly build citations and the bibliography, we use the sphinxcontrib-bibtex extension:
 
-    apt-get install python-sphinx
+        $ pip install sphinxcontrib-bibtex
 
-To properly build citations and the bibliography, we use the sphinxcontrib-bibtex extension:
+To build the documentation just run:
+
+    $ make html
+
+from the main documentation directory (i.e. <vtr_root>/doc).
+
+This will produce the output html in the _build directory.
+
+You can then view the resulting documention with the web-browser of your choice.
+For instance:
+
+    $ firefox _build/index.html
 
-    pip install sphinxcontrib-bibtex
 
 Documentation Layout
--------------------
+--------------------
 
 The root of the VTR documentation is the index.rst file in the current directory.
 
 This file references other files using the toctree directive.
 
-Key sub-systems of VTR have their documentation located in a sub-directy (e.g. vpr, arch), with thier own index.rst.
+Key sub-systems of VTR have their documentation located in a sub-directory (e.g. vpr, arch), with thier own index.rst.
+
+Within each sub-directory there are usually several other .rst files which containing actual documentation for the subsystem.
+Each of these files must be referred to in the sub-system's index.rst in order to be included in the generated documentation.
+
 
-Useful links:
--------------
+Useful Resources:
+-----------------
 
-Re-Structured Text Syntax: 
+Re-Structured Text syntax: 
     http://www.sphinx-doc.org/en/stable/rest.html
 
 Paragraph-level markup: