diff --git a/doc/source/guides.rst b/doc/source/guides.rst
new file mode 100644
index 0000000..c2c7b91
--- /dev/null
+++ b/doc/source/guides.rst
@@ -0,0 +1,68 @@
+Guides
+======
+
+.. warning::
+
+   The guides are point in time contributions, and may not always be
+   up to date with the latest work in devstack.
+
+Walk through various setups used by stackers
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   guides/single-vm
+   guides/single-machine
+   guides/lxc
+   guides/multinode-lab
+   guides/neutron
+   guides/devstack-with-nested-kvm
+   guides/nova
+   guides/devstack-with-lbaas-v2
+
+All-In-One Single VM
+--------------------
+
+Run :doc:`OpenStack in a VM <guides/single-vm>`. The VMs launched in your cloud will be slow as
+they are running in QEMU (emulation), but it is useful if you don't have
+spare hardware laying around. :doc:`[Read] <guides/single-vm>`
+
+All-In-One Single Machine
+-------------------------
+
+Run :doc:`OpenStack on dedicated hardware <guides/single-machine>`  This can include a
+server-class machine or a laptop at home.
+:doc:`[Read] <guides/single-machine>`
+
+All-In-One LXC Container
+-------------------------
+
+Run :doc:`OpenStack in a LXC container <guides/lxc>`. Beneficial for intermediate
+and advanced users. The VMs launched in this cloud will be fully accelerated but
+not all OpenStack features are supported. :doc:`[Read] <guides/lxc>`
+
+Multi-Node Lab
+--------------
+
+Setup a :doc:`multi-node cluster <guides/multinode-lab>` with dedicated VLANs for VMs & Management.
+:doc:`[Read] <guides/multinode-lab>`
+
+DevStack with Neutron Networking
+--------------------------------
+
+Building a DevStack cluster with :doc:`Neutron Networking <guides/neutron>`.
+This guide is meant for building lab environments with a dedicated
+control node and multiple compute nodes.
+
+DevStack with KVM-based Nested Virtualization
+---------------------------------------------
+
+Procedure to setup :doc:`DevStack with KVM-based Nested Virtualization
+<guides/devstack-with-nested-kvm>`. With this setup, Nova instances
+will be more performant than with plain QEMU emulation.
+
+Nova and devstack
+--------------------------------
+
+Guide to working with nova features :doc:`Nova and devstack <guides/nova>`.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 68ec174..c1302eb 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,163 +1,131 @@
-DevStack
-========
+.. Documentation Architecture for the devstack docs.
+
+   It is really easy for online docs to meander over time as people
+   attempt to add the small bit of additional information they think
+   people need, into an existing information architecture. In order to
+   prevent that we need to be a bit strict as to what's on this front
+   page.
+
+   This should *only* be the quick start narrative. Which should end
+   with 2 sections: what you can do with devstack once it's set up,
+   and how to go beyond this setup. Both should be a set of quick
+   links to other documents to let people explore from there.
+
+==========
+ DevStack
+==========
 
 .. image:: assets/images/logo-blue.png
 
 DevStack is a series of extensible scripts used to quickly bring up a
-complete OpenStack environment.  It is used interactively as a
-development environment and as the basis for much of the OpenStack
-project's functional testing.
+complete OpenStack environment based on the latest versions of
+everything from git master.  It is used interactively as a development
+environment and as the basis for much of the OpenStack project's
+functional testing.
 
 The source is available at
 `<https://git.openstack.org/cgit/openstack-dev/devstack>`__.
 
-.. toctree::
-   :glob:
-   :maxdepth: 1
+.. warning::
 
-   overview
-   configuration
-   plugins
-   plugin-registry
-   faq
-   hacking
+   DevStack will make substantial changes to your system during
+   installation. Only run DevStack on servers or virtual machines that
+   are dedicated to this purpose.
 
 Quick Start
------------
+===========
 
-#. Select a Linux Distribution
-
-   Only Ubuntu 14.04 (Trusty), Fedora 22 (or Fedora 23) and CentOS/RHEL
-   7 are documented here. OpenStack also runs and is packaged on other
-   flavors of Linux such as OpenSUSE and Debian.
-
-#. Install Selected OS
-
-   In order to correctly install all the dependencies, we assume a
-   specific minimal version of the supported distributions to make it as
-   easy as possible. We recommend using a minimal install of Ubuntu or
-   Fedora server in a VM if this is your first time.
-
-#. Download DevStack
-
-   ::
-
-       git clone https://git.openstack.org/openstack-dev/devstack
-
-   The ``devstack`` repo contains a script that installs OpenStack and
-   templates for configuration files
-
-#. Configure
-
-   We recommend at least a :ref:`minimal-configuration` be set up.
-
-#. Add Stack User
-
-   Devstack should be run as a non-root user with sudo enabled
-   (standard logins to cloud images such as "ubuntu" or "cloud-user"
-   are usually fine).
-
-   You can quickly create a separate `stack` user to run DevStack with
-
-   ::
-
-       devstack/tools/create-stack-user.sh; su stack
-
-#. Start the install, this will take a few minutes.
-
-   ::
-
-       cd devstack; ./stack.sh
-
-Guides
-======
-
-Walk through various setups used by stackers
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   guides/single-vm
-   guides/single-machine
-   guides/lxc
-   guides/multinode-lab
-   guides/neutron
-   guides/devstack-with-nested-kvm
-   guides/nova
-   guides/devstack-with-lbaas-v2
-
-All-In-One Single VM
---------------------
-
-Run :doc:`OpenStack in a VM <guides/single-vm>`. The VMs launched in your cloud will be slow as
-they are running in QEMU (emulation), but it is useful if you don't have
-spare hardware laying around. :doc:`[Read] <guides/single-vm>`
-
-All-In-One Single Machine
--------------------------
-
-Run :doc:`OpenStack on dedicated hardware <guides/single-machine>`  This can include a
-server-class machine or a laptop at home.
-:doc:`[Read] <guides/single-machine>`
-
-All-In-One LXC Container
--------------------------
-
-Run :doc:`OpenStack in a LXC container <guides/lxc>`. Beneficial for intermediate
-and advanced users. The VMs launched in this cloud will be fully accelerated but
-not all OpenStack features are supported. :doc:`[Read] <guides/lxc>`
-
-Multi-Node Lab
---------------
-
-Setup a :doc:`multi-node cluster <guides/multinode-lab>` with dedicated VLANs for VMs & Management.
-:doc:`[Read] <guides/multinode-lab>`
-
-DevStack with Neutron Networking
---------------------------------
-
-Building a DevStack cluster with :doc:`Neutron Networking <guides/neutron>`.
-This guide is meant for building lab environments with a dedicated
-control node and multiple compute nodes.
-
-DevStack with KVM-based Nested Virtualization
----------------------------------------------
-
-Procedure to setup :doc:`DevStack with KVM-based Nested Virtualization
-<guides/devstack-with-nested-kvm>`. With this setup, Nova instances
-will be more performant than with plain QEMU emulation.
-
-Nova and devstack
---------------------------------
-
-Guide to working with nova features :doc:`Nova and devstack <guides/nova>`.
-
-DevStack Documentation
-======================
-
-Overview
---------
-
-:doc:`An overview of DevStack goals and priorities <overview>`
-
-Configuration
+Install Linux
 -------------
 
-:doc:`Configuring and customizing the stack <configuration>`
+Start with a clean and minimal install of a Linux system. Devstack
+attempts to support Ubuntu 14.04/16.04, Fedora 23/24, CentOS/RHEL 7,
+as well as Debian and OpenSUSE.
 
-Plugins
+If you do not have a preference, Ubuntu 16.04 is the most tested, and
+will probably go the smoothest.
+
+Download DevStack
+-----------------
+
+::
+
+   git clone https://git.openstack.org/openstack-dev/devstack
+
+The ``devstack`` repo contains a script that installs OpenStack and
+templates for configuration files
+
+Create a local.conf
+-------------------
+
+Create a ``local.conf`` file with 4 passwords preset
+
+::
+
+   [[local|localrc]]
+   ADMIN_PASSWORD=secret
+   DATABASE_PASSWORD=$ADMIN_PASSWORD
+   RABBIT_PASSWORD=$ADMIN_PASSWORD
+   SERVICE_PASSWORD=$ADMIN_PASSWORD
+
+This is the minimum required config to get started with DevStack.
+
+Add Stack User
+--------------
+
+Devstack should be run as a non-root user with sudo enabled
+(standard logins to cloud images such as "ubuntu" or "cloud-user"
+are usually fine).
+
+You can quickly create a separate `stack` user to run DevStack with
+
+::
+
+   devstack/tools/create-stack-user.sh; su stack
+
+Start the install
+-----------------
+
+::
+
+   cd devstack; ./stack.sh
+
+This will take a 15 - 20 minutes, largely depending on the speed of
+your internet connection. Many git trees and packages will be
+installed during this process.
+
+Profit!
 -------
 
-:doc:`Extending DevStack with new features <plugins>`
+You now have a working DevStack! Congrats!
 
-FAQ
----
+Your devstack will have installed ``keystone``, ``glance``, ``nova``,
+``cinder``, ``neutron``, and ``horizon``. Floating IPs will be
+available, guests have access to the external world.
 
-:doc:`The DevStack FAQ <faq>`
+You can access horizon to experience the web interface to
+OpenStack, and manage vms, networks, volumes, and images from
+there.
 
-Contributing
-------------
+You can ``source openrc`` in your shell, and then use the
+``openstack`` command line tool to manage your devstack.
 
-:doc:`Pitching in to make DevStack a better place <hacking>`
+You can ``cd /opt/stack/tempest`` and run tempest tests that have
+been configured to work with your devstack.
 
+Going further
+-------------
+
+Learn more about our :doc:`configuration system <configuration>` to
+customize devstack for your needs.
+
+Read :doc:`guides <guides>` for specific setups people have (note:
+guides are point in time contributions, and may not always be kept
+up to date to the latest devstack).
+
+Enable :doc:`devstack plugins <plugins>` to support additional
+services, features, and configuration not present in base devstack.
+
+Get :doc:`the big picture <overview>` of what we are trying to do
+with devstack, and help us by :doc:`contributing to the project
+<hacking>`.
diff --git a/doc/source/site-map.rst b/doc/source/site-map.rst
new file mode 100644
index 0000000..480d6aa
--- /dev/null
+++ b/doc/source/site-map.rst
@@ -0,0 +1,21 @@
+:orphan:
+
+.. the TOC on the front page actually makes the document a lot more
+   confusing. This lets us bury a toc which we can link in when
+   appropriate.
+
+==========
+ Site Map
+==========
+
+.. toctree::
+   :glob:
+   :maxdepth: 3
+
+   overview
+   configuration
+   plugins
+   plugin-registry
+   faq
+   hacking
+   guides