From 44959104281db2a94163e97bde517f9c4f1dee1a Mon Sep 17 00:00:00 2001
From: Isaac Prior <isaac@stackhpc.com>
Date: Mon, 20 May 2019 11:41:27 +0100
Subject: [PATCH] Add welcome page overview doc

Change-Id: I8005dd608bbaed3fcafcce56fc5dd9c307434a77
---
 README.rst                     |  1 -
 doc/source/getting-started.rst | 30 ++++++++++++++++++++++++++++++
 doc/source/index.rst           | 18 +++++++++++++++++-
 doc/source/resources.rst       |  2 ++
 4 files changed, 49 insertions(+), 2 deletions(-)
 create mode 100644 doc/source/getting-started.rst

diff --git a/README.rst b/README.rst
index d4fb28b73..ea6ae16fe 100644
--- a/README.rst
+++ b/README.rst
@@ -1,4 +1,3 @@
-======
 Kayobe
 ======
 
diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst
new file mode 100644
index 000000000..5f2fdad83
--- /dev/null
+++ b/doc/source/getting-started.rst
@@ -0,0 +1,30 @@
+Getting Started
+---------------
+
+We advise new users start by reading the :doc:`Architecture <architecture>`
+documentation first in order to understand Kayobe's various components.
+
+For users wishing to learn interactively we recommend starting at either
+the :doc:`all-in-one overcloud <development/automated>` deployment or
+the :ref:`'A Universe From Nothing' <a-universe-from-nothing>`
+deployment guide.
+
+Once familiar with Kayobe's constituent parts, move on to the
+:doc:`Installation <installation>` section to prepare a baremetal environment
+and then :doc:`Deployment <deployment>` to deploy to it.
+
+* :doc:`Architecture <architecture>` - The function of Kayobe's host and
+  networking components
+* :doc:`Installation <installation>` - The prerequisites and options for
+  installing Kayobe
+* :doc:`Usage <usage>` - An introduction to the Kayobe CLI
+* :doc:`Configuration <configuration/index>` - How to configure Kayobe's
+  various components
+* :doc:`Deployment <deployment>`- Using Kayobe to deploy OpenStack
+* :doc:`Upgrading <upgrading>` - Upgrading from one OpenStack release to
+  another
+* :doc:`Administration <administration/index>` - Post-deploy administration
+  tasks
+* :doc:`Resources <resources>` - External links to Kayobe resources
+* :doc:`Development <development/index>` - Deploying Kayobe development
+  environments
diff --git a/doc/source/index.rst b/doc/source/index.rst
index b3f41d793..1a7e62d5f 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -3,13 +3,29 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+==================================
 Welcome to Kayobe's documentation!
 ==================================
 
+Overview
+========
+
+Welcome to the Kayobe documentation, the official source of information for
+understanding and using Kayobe.
+
+This documentation is maintained at opendev.org
+`here <https://opendev.org/x/kayobe.git>`_. Feedback and contributions welcome,
+see :doc:`contributing <development/contributing>` for information on how.
+
 .. include:: ../../README.rst
 
 Documentation
--------------
+=============
+
+.. include:: getting-started.rst
+
+Contents
+========
 
 .. toctree::
    :maxdepth: 2
diff --git a/doc/source/resources.rst b/doc/source/resources.rst
index 11fea507a..ae9570cac 100644
--- a/doc/source/resources.rst
+++ b/doc/source/resources.rst
@@ -4,6 +4,8 @@ Resources
 
 This section contains links to external Kayobe resources.
 
+.. _a-universe-from-nothing:
+
 A Universe From Nothing
 ========================