docs(): Rename and refactor things so they are better

Author: Devyn Stott

README.md

@@ -3,6 +3,7 @@ A starting spot for python projects. Embracing open source elements.
 
 [![Documentation status](https://readthedocs.org/projects/python-starter/badge/?version=latest)](http://python-starter.readthedocs.io/en/latest/) [![Build Status](https://travis-ci.org/SyntaxRules/python-starter.svg?branch=master)](https://travis-ci.org/SyntaxRules/python-starter) [![codecov](https://codecov.io/gh/SyntaxRules/python-starter/branch/master/graph/badge.svg)](https://codecov.io/gh/SyntaxRules/python-starter)
 
+Documentation: http://python-starter.readthedocs.io/en/latest/
 
 # Project Details
 
@@ -14,7 +15,7 @@ This project follows the structure suggested in [Jan-Philip Gehrcke's Blog](http
 
 This project uses [Semver](http://semver.org/) as its versioning scheme.
 
-## Tests.
+## Tests
 
 Basic acceptance tests are in the tests folder. You can run these tests by running `python setup.py test`. The unit tests are in line with the code. You can run all the tests with `python -m pytest .`.
 
@@ -25,3 +26,9 @@ Coverage is also determined by TravisCI and reported to [CodeCov](https://codeco
 ## Documentation
 
 Documentation is inline (like unit tests) and deployed with [Read the Docs](http://python-starter.readthedocs.io/en/latest/). When editing code, please include documentation for your changes. Add any new files to the `mkdocs.yml` file. The documentation is automatically built and installed.
+
+The documentation is found here: http://python-starter.readthedocs.io/en/latest/
+
+You can test the docs locally by installing [mkdocs](http://www.mkdocs.org/) and running `mkdocs serve` in the root directory of the project source. This will launch a server locally that you can use to view what the docs will look like when deployed. The pages update automatically when changes are made.
+
+You can add a page to the documentation by editing the *mkdocs.yml* file in the source repo. See [Adding Pages](http://www.mkdocs.org/#adding-pages).

mkdocs.yml

@@ -5,5 +5,6 @@ docs_dir: 'starter'
 pages:
     - 'Overview': 'index.md'
     - 'User Guide':
-        - 'Quick Start': 'docs/user_guide/article1.md'
-        - 'Service API': 'docs/user_guide/article2.md'
+        - 'Quick Start': 'docs/quick-start.md'
+        - 'Installation Instructions': 'docs/installation-instructions.md'
+    - 'License': 'docs/license.md'

starter/README.md

@@ -0,0 +1,5 @@
+# Starter source and documentation
+
+The source code for the documentation page is found in index.md (in this same directory).
+
+The source code for this repo is found in this folder. See the docs for more information.

starter/docs/README.md

@@ -0,0 +1,3 @@
+# Installation instructions
+
+This section covers advanced installations instructions, including how to build from source.

starter/docs/installation-instructions.md

@@ -0,0 +1,3 @@
+# Quick Start
+
+To get started using this project:

starter/docs/quick-start.md

@@ -1,5 +1,5 @@
 # Overview
 
-This is the project overview
+This is the overview page and the default index page of the documentation.
 
-Wit foo bar
+For development details (i.e project structure, tests and versioning) see the README.md file in the src repository.