Including text and graphic placeholders for the user and config guides. (I like apostrophes'')

This patch contains the introduction and framing text for the user and config guide.
Work is required to add the scenario/feature mapping section and information.

Change-Id: I71c9fa7cfbac2d0100c743a8855df4a02cc7482c
Signed-off-by: ChristopherPrice <christopher.price@ericsson.com>

14 files changed, 206 insertions, 14 deletions

diff --git a/docs/configguide/configoptions.rst b/docs/configguide/configoptions.rst
index 2e56fa08d..bf3dc3d08 100644
--- a/docs/configguide/configoptions.rst
+++ b/docs/configguide/configoptions.rst
@@ -1,5 +1,22 @@
 Configuration Options
 =====================
 
-Add an overview section and reference table for installers and features.
+OPNFV provides a variety of virtual infrastructure deployments called scenarios designed to
+host virtualised network functions (VNF's).  Each scenario provide specific capabilities and/or
+components aimed to solve specific problems for the deployment of VNF's.  A scenario may include
+components such as OpenStack, OpenDaylight, OVS, KVM etc. where each scenario will
+include different source components or configurations.
 
+OPNFV Scenario's
+----------------
+
+Each OPNFV scenario provides unique features and capabilities, it is important to understand
+your target platform capabilities before installing and configuring your target scenario.
+This configuration guide outlines how to install and configure components in order to enable
+the features you require.
+
+.. include:: ../scenario/scenariomatrix.rst
+
+This document will describe how to install and configure your target OPNFV scenarios.
+Remember to check the associated validation procedures section following your installation for
+details of the use cases and tests that have been run.
diff --git a/docs/images/brahmaputrafeaturematrix.jpg b/docs/images/brahmaputrafeaturematrix.jpg
new file mode 100644
index 000000000..26d3387dc
--- /dev/null
+++ b/docs/images/brahmaputrafeaturematrix.jpg
diff --git a/docs/images/brahmaputrascenariomatrix.jpg b/docs/images/brahmaputrascenariomatrix.jpg
new file mode 100644
index 000000000..d1e6949ad
--- /dev/null
+++ b/docs/images/brahmaputrascenariomatrix.jpg
diff --git a/docs/scenario/featurematrix.rst b/docs/scenario/featurematrix.rst
new file mode 100644
index 000000000..5b79028d8
--- /dev/null
+++ b/docs/scenario/featurematrix.rst
@@ -0,0 +1,27 @@
+Each scenario provides a set of platform capabilities and features that it supports.  It is
+possible to identify which features are provided by reviewing the scenario name, however
+not all features and capabilities are discernible from the name itself.
+
+Scenario Naming
+^^^^^^^^^^^^^^^
+
+In OPNFV, scenarios are identified by short scenario names.  These names follow a scheme that
+identifies the key components and behaviours of the scenario, the rules for scenario naming are as follows:
+
+  os-[controller]-[feature]-[mode]-[option]
+
+For example: *os-nosdn-kvm-noha* provides an OpenStack based deployment using neutron including
+the OPNFV enhanced KVM hypervisor.
+
+The [feature] tag in the scenario name describes the main feature provided by the scenario.
+This scenario may also provide support for advanced fault management features which is not apparent
+in the scenario name.  The following section describes the features available in each scenario.
+
+Brahmaputra feature support matrix
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following table provides an overview of the available scenarios and supported features
+in the Brahmaputra release of OPNFV.
+
+.. image:: ../images/brahmaputrafeaturematrix.jpg
+   :alt: OPNFV Brahmaputra Feature Matrix
diff --git a/docs/scenario/scenariointro.rst b/docs/scenario/scenariointro.rst
new file mode 100644
index 000000000..dd808432b
--- /dev/null
+++ b/docs/scenario/scenariointro.rst
@@ -0,0 +1,13 @@
+OPNFV Scenarios
+---------------
+
+The OPNFV project provides an integration and deployment environment for a variety of components
+that can make up a virtualisation platform.  OPNFV identifies these variations on the composition of
+the platform as scenarios.
+
+A scenario in OPNFV can be defined as "a deployment of a specific set of platform components".  The
+composition of a scenario may include specific SDN controller technologies, specific accelerate
+switching technologies, or even specific configurations of components to achieve targeted platform
+capabilities.  Each scenario behaves differetly and it is important to understand the behaviour you
+want in order to target the specific scenario you wish to deploy prior to working with the
+OPNFV platform.
diff --git a/docs/scenario/scenariomatrix.rst b/docs/scenario/scenariomatrix.rst
new file mode 100644
index 000000000..5769fa8d9
--- /dev/null
+++ b/docs/scenario/scenariomatrix.rst
@@ -0,0 +1,77 @@
+Scenarios are implemented as deployable compositions through integration with an installation tool.
+OPNFV supports multiple installation tools and for any given release not all tools will support all
+scenarios.  While our target is to establish parity across the installation tools to ensure they
+can provide all scenarios, the practical challenge of achieving that goal for any given feature and
+release results in some disparity.
+
+Scenario Naming
+^^^^^^^^^^^^^^^
+
+In OPNFV scenarios are identified by short scenario names, these names follow a scheme that
+identifies the key components and behaviours of the scenario.  The rules for scenario naming are as follows:
+
+  os-[controller]-[feature]-[mode]-[option]
+
+Details of the fields are
+  * os: mandatory
+
+    * Refers to the platform type used
+    * possible value: os (OpenStack)
+
+* [controller]: mandatory
+
+    * Refers to the SDN controller integrated in the platform
+    * example values: nosdn, ocl, odl, onos
+
+  * [feature]: mandatory
+
+    * Refers to the feature projects supported by the scenario
+    * example values: nofeature, kvm, ovs
+
+  * [mode]: mandatory
+
+    * Refers to the deployment type, which may include for instance high availability
+    * possible values: ha, noha
+
+  * [option]: optional
+
+    * Used for the scenarios those do not fit into naming scheme.
+    * The optional field in the short scenario name should not be included if there is no optional scenario.
+
+Some examples of supported scenario names are:
+
+  * os-nosdn-kvm-noha
+
+    * This is an OpenStack based deployment using neutron including the OPNFV enhanced KVM hypervisor
+
+  * os-odl_l2-nofeature-ha
+
+    * This is an OpenStack deployment in high availability mode including OpenDaylight layer2 networking
+
+  * os-onos-kvm_ovs-noha
+
+    * This is an OpenStack deployment using ONOS including OPNFV enhanced KVM and OVS versions
+
+Installing your scenario
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two main methods of deploying your target scenario, one method is to follow this guide which will
+walk you through the process of deploying to your hardware using scripts or ISO images, the other method is
+to set up a Jenkins slave and connect your infrastructure to the OPNFV Jenkins master.
+
+For the purposes of evaluation and development a number of Brahmaputra scenarios are able to be deployed
+virtually to mitigate the requirements on physical infrastructure.  Details and instructions on performing
+virtual deployments can be found in the installer specific installation instructions.
+
+To set up a Jenkins slave for automated deployment to your lab, refer to the `Jenkins slave connect guide.
+<http://artifacts.opnfv.org/brahmaputra.1.0/docs/opnfv-jenkins-slave-connection.brahmaputra.1.0.html>`_
+
+Brahmaputra scenario overeview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following table provides an overview of the installation tools and available scenario's
+in the Brahmaputra release of OPNFV.
+
+.. image:: ../images/brahmaputrascenariomatrix.jpg
+   :alt: OPNFV Brahmaputra Scenario Matrix
+
diff --git a/docs/scenario/scenariovalidation.rst b/docs/scenario/scenariovalidation.rst
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/scenario/scenariovalidation.rst
diff --git a/docs/userguide/abstract.rst b/docs/userguide/abstract.rst
index b7b22aa5b..502c3fb5f 100644
--- a/docs/userguide/abstract.rst
+++ b/docs/userguide/abstract.rst
@@ -1,8 +1,11 @@
 Abstract
 --------
 
-This document provides guidance and instructions for using
-features delivered in the Brahmaputra release of OPNFV.
+OPNFV is a collaborative project aimed at providing a variety of virtualisation
+deployments intended to host applications serving the networking and carrier industry.
+This document provides guidance and instructions for using platform features designed
+to support these applications, made available in the Brahmaputra release of OPNFV.
 
-This document provides a guide for the usage of features and the
-needed selection of tools and components as prerequisites.
+This document is not intended to replace or replicate documentation from other open
+source projects such as OpenStack or OpenDaylight, rather highlight the features and
+capabilities delivered through the OPNFV project.
diff --git a/docs/userguide/general-system.rst b/docs/userguide/general-system.rst
index 3865f3dd7..b62d723c9 100644
--- a/docs/userguide/general-system.rst
+++ b/docs/userguide/general-system.rst
@@ -1,5 +1,5 @@
-General system usage
-====================
+Usage of platform components
+============================
 
 This section of the user guide provides general system component user guides and references.
 This provides user information for common components of the platform where as a user you may
diff --git a/docs/userguide/introduction.rst b/docs/userguide/introduction.rst
index a492c6efb..9ac9f0814 100644
--- a/docs/userguide/introduction.rst
+++ b/docs/userguide/introduction.rst
@@ -1,4 +1,59 @@
-OPNFV User Guide
-================
+Overview
+========
 
-Outline the structure and composition of the User Guide in this section.
+OPNFV provides a variety of virtual infrastructure deployments designed to
+host virtualised network functions (VNFs).  This guide intends to help users of
+the platform leverage the features and capabilities delivered by the OPNFV project.
+
+OPNFV Continuous Integration builds, deploys and tests combinations of virtual
+infrastructure components in what are defined as scenarios.  A scenario may include
+components such as OpenStack, OpenDaylight, OVS, KVM etc. where each scenario will
+include different source components or configurations.  Scenarios are designed to
+enable specific features and capabilities in the platform that can be leveraged by the
+OPNFV user community.
+
+OPNFV Scenarios
+----------------
+
+Each OPNFV scenario provides unique features and capabilities, it is important to
+ensure you have a scenario deployed on your infrastructure that provides the right capabilities
+for your needs before working through the user guide.
+
+This user guide outlines how to work with key components and features in the platform,
+each feature description section will indicate the scenarios that provide the components
+and configurations required to use it.
+
+.. include:: ../scenario/featurematrix.rst
+
+For details on which scenario's are best for you and how to install and configure them
+on your infrastructure the `OPNFV Configuration guide
+<http://artifacts.opnfv.org/opnfvdocs/docs/configguide/index.html>`_ provides a definitive
+reference.
+
+The user guide will describe how to enable and utilise features and use cases implemented and
+tested on deployed OPNFV scenarios.  For details of the use cases and tests that have been run
+you should check the validation procedures section of the features configuration guide.  This will
+provide information about the specific use cases that have been validated and are working
+on your deployment.
+
+General usage guidelines
+------------------------
+
+The user guide for OPNFV features and capabilities provide step by step instructions
+for using features that have been configured according to the installation and configuration
+instructions.
+
+This guide is structured in a manner that will provide usage instructions for each feature in its own
+section.  Identify the feature capability you would like to leverage and read through that user guide
+section to understand the available usage.  The combination of platform features, if available in a given
+scenario and not otherwise indicated, should function by following each features section.
+Dependencies between features will be highlighted in the user guide text.
+
+You may wish to use the platform in a manner that the development team have not foreseen, or
+exercise capabilities not fully validated on the platform.  If you experience issues leveraging the
+platform for the uses you have envisioned the `OPNFV user mailing list <"mailto:opnfv-user@lists.opnfv.org">`_
+provides a mechanism to establish a dialog with the community to help you overcome any issues identified.
+
+It may be that you have identified a bug in the system, or that you are trying to execute a use case
+that has not yet ben implemented.  In either case OPNFV is in essence a development project
+looking to ensure the required capabilities for our users are available.
diff --git a/docs/userguide/onos.rst b/docs/userguide/onos.rst
index 0806caae5..d4fdb59c1 100644
--- a/docs/userguide/onos.rst
+++ b/docs/userguide/onos.rst
@@ -1,5 +1,5 @@
 ONOS User Guide
-=======================
+---------------
 
 Add ONOS specific user guide information here.
 Needs to include OPNFV default ports and addresses and
diff --git a/docs/userguide/opendaylight.rst b/docs/userguide/opendaylight.rst
index 6e43c05c5..3616307e7 100644
--- a/docs/userguide/opendaylight.rst
+++ b/docs/userguide/opendaylight.rst
@@ -1,5 +1,5 @@
 OpenDaylight User Guide
-=======================
+-----------------------
 
 Add opendaylight specific user guide information here.
 Needs to include OPNFV default ports and addresses and
diff --git a/docs/userguide/openstack.rst b/docs/userguide/openstack.rst
index daeb5240f..069dc4b76 100644
--- a/docs/userguide/openstack.rst
+++ b/docs/userguide/openstack.rst
@@ -1,5 +1,5 @@
 OpenStack User Guide
-====================
+--------------------
 
 Add openstack specific user guide information here.
 Needs to include OPNFV default ports and addresses and
diff --git a/docs/userguide/ovs.rst b/docs/userguide/ovs.rst
index 9209ac61c..10e65baeb 100644
--- a/docs/userguide/ovs.rst
+++ b/docs/userguide/ovs.rst
@@ -1,5 +1,5 @@
 OVS User Guide
-==============
+--------------
 
 Add OVS specific user guide information here.
 Needs to include OPNFV default ports and addresses and