Updating the overview doc with recent comments.

Change-Id: I181279f9b0a4330bb98a3e0d40ecb2687d976b92
Signed-off-by: ChristopherPrice <christopher.price@ericsson.com>
(cherry picked from commit 4cb9b020b922c090061a2dee77fa8ad77394d7b9)

6 files changed, 59 insertions, 83 deletions

diff --git a/docs/configguide/installer-config.rst b/docs/configguide/installer-config.rst
index 3569d4ed2..a88d1f50e 100644
--- a/docs/configguide/installer-config.rst
+++ b/docs/configguide/installer-config.rst
@@ -6,6 +6,15 @@
 Installer Configuration
 =======================
 
+Installing the OPNFV platform requires either a physical environment as defined in the
+Pharos lab specification, or a virtual infrastructure.  When configuring a physical infrastructure
+it is strongly advised to follow the Pharos configuration material.
+
+.. toctree::
+
+    pharos-config
+
+
 The following sections describe the per installer configuration options.
 Further details for each installer are captured in the referred project documentation.
 
diff --git a/docs/configguide/pharos-config.rst b/docs/configguide/pharos-config.rst
new file mode 100644
index 000000000..013e21b34
--- /dev/null
+++ b/docs/configguide/pharos-config.rst
@@ -0,0 +1,5 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. include:: ../projects/pharos/configguide/configguide.rst
+.. include:: ../projects/pharos/configguide/jumpserverinstall.rst
diff --git a/docs/platformoverview/deploymenttools.rst b/docs/platformoverview/deploymenttools.rst
index a8037184a..f3693c0ae 100644
--- a/docs/platformoverview/deploymenttools.rst
+++ b/docs/platformoverview/deploymenttools.rst
@@ -18,7 +18,7 @@ RDO manager is a Triple-O based installation tool.
 Triple-O is an image based life cycle deployment tool that is a member of the OpenStack Big Tent Governance.
 Apex uses Centos on all target platforms and can deploy all SDN controllers.
 Find more information at
-`OpenStack Wiki for Triple-O <https://wiki.openstack.org/wiki/Tripleo>`_ and the OPNFV user guide and
+`OpenStack Wiki for Triple-O <https://wiki.openstack.org/wiki/TripleO>`_ and the OPNFV user guide and
 config guide.
 
 **Compass** is an installer project based on open source project Compass, which provides automated deployment
@@ -27,7 +27,7 @@ It can be considered as what the LiveCD to a single box for a pool of servers â€
 Compass is based on Ansible.
 It can deploy Ubuntu or Centos as target operating system and ODL and ONOS as SDN controllers.
 Find more information at
-`OpenStack Wiki for Compass <https://wiki.openstack.org/wiki/Complass>`_ and the OPNFV user guide and
+`OpenStack Wiki for Compass <https://wiki.openstack.org/wiki/Compass>`_ and the OPNFV user guide and
 config guide.
 
 **Fuel** is an installer project based on the Fuel OpenStack open source project
@@ -38,10 +38,10 @@ Find more information at
 `OpenStack Wiki for Fuel <https://wiki.openstack.org/wiki/Fuel>`_ and the OPNFV user guide and
 config guide.
 
-**Joid** installer utilizes the technology developed in Juju and MAAS.
+**Joid** is an installer utilizes the technology developed in Juju and MAAS.
 Juju allows you to deploy, configure, manage, maintain, and scale
 cloud services quickly and efficiently on public clouds, as well as on physical servers,
 OpenStack, and containers. Together with MAAS hardware usage can be optimized.
 For more info on Juju and MAAS, please visit `<https://jujucharms.com/>`_,
 `<http://maas.ubuntu.com>`_ and the
-`Joid Userguide <http://artifacts.opnfv.org/joid/docs/userguide/userguide.pdf>`_.
+`Joid Userguide <http://artifacts.opnfv.org/joid/brahmaputra/docs/userguide/index.html>`_.
diff --git a/docs/platformoverview/introduction.rst b/docs/platformoverview/introduction.rst
index 0c878afbb..eab30e9b1 100644
--- a/docs/platformoverview/introduction.rst
+++ b/docs/platformoverview/introduction.rst
@@ -12,7 +12,7 @@ Introduction
 
 OPNFV is an integration effort that takes outputs from several open source communities to build a NFV platform. This task of integration leads to providing different kinds of output to its users.
 
-The primary goal of the OPNFV project is the **target software platform**, which is a integrated solution
+The primary goal of the OPNFV project is the target software platform, which is a integrated solution
 of a set of components/building blocks of the ETSI ISG NFV reference architecture.
 In the Brahmaputra release, this is limited to the NFVI and VIM blocks.
 OPNFV users will be able to deploy their VNFs there using some MANO solution.
@@ -22,9 +22,9 @@ possible and a subset is provided and tested by the Brahmaputra release. These s
 are called here scenarios.
 
 Besides the target software platform, OPNFV provides a set of tools that helps the user
-deploy this target software platform on a set of servers. These tools are called
-**installers**. Brahmaputra provides multiple options here. Naturally the different installers
-have different capabilities, that is they support deployment of different **scenarios**.
+deploy this target software platform on a set of servers. These tools are installers.
+Brahmaputra provides multiple options here. Naturally the different installers
+have different capabilities, that is they support deployment of different scenarios.
 
 The installers allow users to deploy OPNFV target software platform on a bare metal environment
 or a set of virtual machines. In both cases, some hosts (bare metal or virtual) will act
@@ -36,33 +36,33 @@ The jump server also can be bare metal or virtual.
 This configuration - jump servers and a set of typically 5 nodes to run the target software platform -
 is also described as part of an OPNFV release. This allows the users to build their own labs
 accordingly and deploy OPNFV easily. A lab compliant to this description sometimes is called
-**"Pharos-compliant"** after the OPNFV project providing the lab description.
+"Pharos-compliant" after the OPNFV project providing the lab description.
 
-Another major part of the OPNFV release is a **testing framework** and test cases.
+Another major part of the OPNFV release is a testing framework and test cases.
 This test framework allows users to verify their deployment of the OPNFV target software platform.
 It will execute and test major functions of the platform relevant to NFV applications (VNFs) so
 the user can be confident that VNFs can successfully run.
 
-Of course, the OPNFV releases come with the necessary **documentation**, describing
-target software platform, deployment tools, tests, etc. in their architecture, configuration and usage.
+OPNFV releases come with the necessary documentation describing
+target software platform, deployment tools, test cases, etc. in their architecture, configuration and usage.
 The most important documents here are configuration guides and user guides that help to set up
 a OPNFV deployment and use it.
 
-The OPNFV project takes major effort to provide **lab environments** to the community.
+The OPNFV project takes major effort to provide lab environments to the community.
 The OPNFV community labs of course need to be Pharos-compliant. They are used for OPNFV development
 tasks and release creation, but should also provide users with the opportunity to run their own
 OPNFV tests. OPNFV community labs are not part of a OPNFV release.
 Please find more information on the labs in the
-`Pharos project documentation <http://artifacts.opnfv.org/pharos/docs/index.html>`_.
+`Pharos project documentation <http://artifacts.opnfv.org/pharos/brahmaputra/docs/index.html>`_.
 
-We should also mention that OPNFV works on **requirements** of open source projects used in OPNFV to
+We should also mention that OPNFV works on requirements of open source projects used in OPNFV to
 make these projects better suitable for NFV telco carrier use cases.
 These requirements are described in requirement documents and also forwarded
 to the "upstream" projects in the format required by these projects.
 These requirement documents are not bound to OPNFV releases.
 
 OPNFV bundles the target software, installers, documentation, test cases and lab
-description to **releases**.
+description to releases.
 
 This overview document introduces these components and scenarios on a high level and
 points you to more detailed documentation.
diff --git a/docs/platformoverview/softwarearchitecture.rst b/docs/platformoverview/softwarearchitecture.rst
index a3e815ec5..2f98f42ee 100644
--- a/docs/platformoverview/softwarearchitecture.rst
+++ b/docs/platformoverview/softwarearchitecture.rst
@@ -6,27 +6,25 @@
 OPNFV Platform Architecture
 ===========================
 
-.. ==> Add reference links from https://wiki.opnfv.org/releases/brahmaputra/releasedocs
-
-.. ==> All links should point to release docs, not to OPNFV-Wiki or artifacts.
-
+The OPNFV project addresses a number of aspects in the development of a consistent virtualization
+platform including common hardware requirements, software architecture and installed state.
+The platform architecture as the OPNFV project approaches it is dicussed in the following sections.
 
 OPNFV Lab Infrastructure
 ========================
 
 The `Pharos Project <https://www.opnfv.org/developers/pharos>`_ provides a lab infrastructure
 that is geographically and technically diverse.
-Labs instantiate **bare-metal** and **virtual** environments that are accessed remotely by the
-community and used for OPNFV platform and feature development, builds, deploys and testing.
-This will greatly assist in developing a highly robust and stable OPNFV platform
+Labs instantiate bare-metal and virtual environments that are accessed remotely by the
+community and used for OPNFV platform and feature development, build, deploy and testing.
+This helps in developing a highly robust and stable OPNFV platform
 with well understood performance characteristics.
 
 Community labs are hosted by OPNFV member companies on a voluntary basis.
 The Linux Foundation also hosts an OPNFV lab that provides centralised CI
 and other production resources which are linked to community labs.
 Future lab capabilities will include the ability easily automate deploy and test of any
-OPNFV install scenario in any lab environemnt as well as a *Virtual Lab* for
-developer on-boarding with minimal effort.
+OPNFV install scenario in any lab environemnt as well as on a virtual infrastructure.
 
 .. ==> I am not sure this is the best place to include this.
 
@@ -35,22 +33,17 @@ Software architecture
 =====================
 
 This section will provide information which upstream projects, versions and components are
-integrated in the release to implement OPNFV requirement. You can find a requirement list
-`here <http://artifacts.opnfv.org/genesisreq/docs/requirements.pdf>`_.
+integrated in the release to implement OPNFV requirement. You can find the list of common
+requirements for deployment tools here:
+http://artifacts.opnfv.org/genesisreq/brahmaputra/requirements/requirements.pdf.
 
 OpenStack
 ---------
 
 .. ==> didn't understand Chris' suggestion about reducing the heading level for these sub-topics
 
-OPNFV uses OpenStack as cloud management system.
-Brahmaputra is based on OpenStack Liberty Release.
-The set of sub-projects varies slightly depending on the installer.
-
-.. ==> If possible replace the list of OpenStack components here by a link to an
-.. appropriate document
-.. (http://artifacts.opnfv.org/genesisreq/review/10155/requirements/component-support.html
-.. was suggested, but this is different infomation.)
+OPNFV integrates OpenStack as cloud management system where Brahmaputra uses the OpenStack Liberty Release.
+The set of sub-projects deployed in a brahmaputra platform varies slightly depending on the installer and scenario.
 
 The following table shows which components are deployed.
 
@@ -76,12 +69,6 @@ The following table shows which components are deployed.
 | swift      | object-store   | Available | ---       | Available | Available |
 +------------+----------------+-----------+-----------+-----------+-----------+
 
-.. This table is created by outputs from jenkins functest log, components registering at keystone
-.. would prefer a table per scenario.
-
-Some of the sub-projects are not deployed in all scenarios.
-
-.. end of the part to be replaced by link if possible.
 
 Note that additional components of OpenStack are used as part of deployment tools and test frameworks
 (Fuel, Tempest, Rally).
@@ -105,16 +92,13 @@ SDN Controllers
 ---------------
 
 OPNFV Brahmaputra release supports different SDN controllers.
-Some scenarios don't use an SDN controller but rely just on **Neutron** networking capabilities.
+Some scenarios don't use an SDN controller but rely just on Neutron networking capabilities.
 
-Depending on the SDN controller you are using, the featureset will vary.
-Brahmaputra also provides scenarios without an SDN controller, just using OpenStack Neutron.
+Depending on the SDN controller you are using, the featureset available will vary.  More
+information on feature support and scenarios can be found in the Brahmaputra configuration and
+user guides.  Brahmaputra also provides scenarios without an SDN controller, just using OpenStack Neutron.
 
-The OpenDaylight project is a collaborative open source project that aims to accelerate
-adoption of Software-Defined Networking (SDN) and Network Functions Virtualization
-(NFV) with a transparent approach that fosters new innovation.
-
-**OpenDaylight** is an SDN controller that aims to accelerate
+OpenDaylight is an SDN controller aiming to accelerate
 adoption of Software-Defined Networking (SDN) and Network Functions Virtualization
 (NFV) with a transparent approach that fosters new innovation.
 OpenDaylight runs within a JVM and is installed in OPNFV within a container and integrated with OpenStack
@@ -123,7 +107,7 @@ You can find more information about OpenDaylight among the release artifacts at
 `Downloads page <https://www.opendaylight.org/downloads>`_.
 Please ensure you are using the Beryllium documentation.
 
-**ONOS** is an SDN controller written in Java with a distributed architecture with special focus to
+ONOS is an SDN controller written in Java with a distributed architecture with special focus to
 support scalability, fault tolerance and hardware and software upgrades without
 interrupting network traffic.
 More information on the internal design of ONOS may be found in
@@ -133,11 +117,11 @@ More information on the internal design of ONOS may be found in
 ONOS is integrated to OPNFV using a framework ONOSFW and Neutron plugins. Details can be found in the
 ONOS specific OPNFV documents,
 
-`Design guide <http://artifacts.opnfv.org/onosfw/brahmaputra/docs/design/design.pdf>`_,
-`User guide <http://artifacts.opnfv.org/onosfw/brahmaputra/docs/userguide/index.html>`_ and
-`Config guide <http://artifacts.opnfv.org/onosfw/brahmaputra/docs/configguide/index.html>`_.
+`Design guide <http://artifacts.opnfv.org/onosfw/brahmaputra/design/design.pdf>`_,
+`User guide <http://artifacts.opnfv.org/onosfw/brahmaputra/userguide/index.html>`_ and
+`Config guide <http://artifacts.opnfv.org/onosfw/brahmaputra/configguide/index.html>`_.
 
-.. **OpenContrail** SDN controller will be supported in the next drop of the Brahmaputra release.
+.. OpenContrail SDN controller will be supported in the next drop of the Brahmaputra release.
 
 
 Data Plane
@@ -147,15 +131,13 @@ OPNFV extends Linux's virtual networking capabilies by using virtual switch
 and router components including improving those components by requirements
 specific to telco use cases.
 
-For instance some scenarios use **OpenVSwich**
+For instance some scenarios use OpenVSwitch
 to replace Linux bridges as it offers advantages in terms of mobility, hardware
 integration and use by network controllers. OPNFV leverages these by upgrade
 to a specific installation using user-space datapath. This includes changes to
 other dataplane components, including libvirt, qemu, DPDK etc.
 Please find more information in
-`OVSNFV User's Guide <http://artifacts.opnfv.org/ovsnfv/docs/userguides/userguides.pdf>`_
-
-.. ==> need input, if we mention other components
+`OVSNFV User's Guide <http://artifacts.opnfv.org/ovsnfv/brahmaputra/docs/userguides/userguides.pdf>`_
 
 Other Components
 ----------------
@@ -222,26 +204,6 @@ The following scenarios are supported, some of them can be deployed using differ
 * nosdn-kvm-ha
 * nosdn-ovs_kvm-ha
 
-Please find more information at
-`<https://wiki.opnfv.org/functextnexttaks>`_
-
-.. ==> As soon as better information is available, the list can be replaced by a link to e.g.
-.. http://artifacts.opnfv.org/opnfvdocs/brahmaputra/docs/configguide/configoptions.html#opnfv-scenario-s.
-
-
-.. Dynamic View
-.. ============
-
-.. Editors note: we might skip this section completely for Brahmaputra.
-
-.. Or we provide rather short statements. In later versions, we have to describe which
-.. software is involved in which way during:
-
-.. * VNF Life Cycle (onboarding, instantiate, scaling): we can reference to other documents
-.. * Hardware Life Cycle (mainly how to add compute nodes, but also other cases)
-.. * ...
-
-
-
-
+Please find more information at:
+http://artifacts.opnfv.org/opnfvdocs/brahmaputra/configguide/configoptions.html#opnfv-scenario-s.
 
diff --git a/docs/platformoverview/testcasesframework.rst b/docs/platformoverview/testcasesframework.rst
index 301e1e0b4..985929482 100644
--- a/docs/platformoverview/testcasesframework.rst
+++ b/docs/platformoverview/testcasesframework.rst
@@ -38,7 +38,7 @@ The scope of Functest and relevant test cases can be found in its
 
 In Brahmaputra, Functest is focusing on OpenStack and SDN controllers deployment testing.
 Its testing framework combines a number of testing tools
-to verify the key components of OPNFV platform running successfully.
+to verify the key components of the OPNFV platform are running successfully.
 For example, Rally and Tempest are integrated for OpenStack basic functional testing and benchmark,
 Robot is used for ODL testing, and Teston is integrated for ONOS testing.
 Besides these, Functest also includes tests by deploying candidate VNFs such as vPing and vIMS, and testing their basic functionality.
@@ -54,7 +54,7 @@ Yardstick is also a flexible testing framework supporting OPNFV feature testing
 Projects can plug in their test cases for specific features easily.
 
 The detail of Yardstick project can be found in the
-`yardstick user guide <http://artifacts.opnfv.org/yardstick/brahmaputra/docs/user_guides_framework/user_guides_framework.pdf>`_.
+`yardstick user guide <http://artifacts.opnfv.org/yardstick/brahmaputra/user_guides_framework/user_guides_framework.pdf>`_.
 
 There are two types of test cases in Yardstick: Yardstick generic test cases and OPNFV feature test cases.
 Yardstick generic test cases include basic characteristics benchmarking in compute/storage/network area.
@@ -62,7 +62,7 @@ OPNFV feature test cases include basic telecom feature testing from OPNFV projec
 for example nfv-kvm, sfc, ipv6, Parser, Availability and SDN VPN.
 
 All of the Yardstick test cases are listed on
-`<http://artifacts.opnfv.org/yardstick/docs/configguide_yardstick_testcases/03-list-of-tcs.html>`_
+`<http://artifacts.opnfv.org/yardstick/brahmaputra/docs/configguide_yardstick_testcases/03-list-of-tcs.html>`_
 
 
 Additional Testing