Add introductory material to the StarlingX documentation

This change is the first round of new documents and cleanup of
the "StarlingX" Introduction section of the documentation.

* Created a new "Product Introduction" document.
* Added a new "Consuming StarlingX" document.
* Added a new "Key Concepts" document.
* And cleaned up some of the other document names to make them
  fit in the TOC text box.

Story: 2005002

Change-Id: Ibe2023028c749a18fd83e610519350cf9058127d
Signed-off-by: Bruce Jones <bruce.e.jones@intel.com>

doc/source/introduction/concepts.rst

@@ -0,0 +1,84 @@
+============
+Key concepts
+============
+
+The following are some of key concepts and terminology that are
+commonly used in the StarlingX community and in this documentation.
+
+Basic Terms
+-----------
+
+Node
+  A computer which is usually a server-class system
+
+Virutal Machines
+  An instance of a node provided by software (a hypervisor)
+  which runs within the host operating system and hardare.
+
+Bare Metal
+  A node running without hypervisors (e.g. application workloads run
+  directly on the operating system which runs directly on the hardware).
+
+Controller
+  A node within a StarlingX Edge Cloud that runs the cloud
+  management software ("control plane"). There can be
+  either one or two Controller nodes in a StarlingX Edge Cloud.
+
+Compute or Worker
+  A node within a StarlingX Edge Cloud that is dedicated to running
+  application workloads. There can be zero to ninety-nine Compute
+  nodes in a StarlingX Edge Cloud.
+
+Storage
+  A node within a StarlingX Edge Cloud that is dedicated to providing
+  file and object storage to application workloads. There can be zero
+  or more Storage nodes within a StarlingX Edge Cloud.
+
+Deployment options
+------------------
+
+StarlingX provides a pre-defined set of standard configurations. These
+configurations are:
+
+All-in-one Simplex ("Simplex" or "AIO-SX")
+  The Simplex configuration runs all Edge Cloud functions (control,
+  storage, and application workloads) on one node. This configuration
+  is intended for very small and physically isolated Edge sites
+  that do not require High Availability.
+
+All-in-one Duplex ("Duplex" or "AIO-DX")
+  The Duplex configuration runs all Edge Cloud functions (control,
+  storage, and application workloads) on one node, but there is
+  a second node in the system for Active / Standby based
+  High Availability for all platform and application services.
+
+All-in-one Duplex with up to 4 computes
+  This configuration extends the Duplex configuration
+  by providing a bit more flexibility, In particular it allows
+  a small number of
+  compute nodes to be added to the Edge Cloud after it has
+  been created.
+
+Standard with Controller Storage
+  This configuration allows for 1 or 2 Controller nodes that
+  also provide Storage for the Edge Cloud. The configuration
+  also allows for between 1 and 99
+  Compute nodes to run application workloads. This configuration
+  works best for Edge Clouds with smaller Storage needs.
+
+Standard with Dedicated Storage
+  This configuration has dedicated Storage nodes in addition
+  to the Controller and Compute nodes. You can use this
+  configuration for Edge Clouds that require larger amounts of Storage.
+
+Standard with Ironic
+  This configuration extends the Standard configurations
+  to add the OpenStack Ironic service, which allows application
+  workloads to run on Bare Metal servers.
+
+Multi-Region
+  TBD
+
+Distributed Cloud
+  An upcoming feature for StarlingX that will allow one
+  controller to control a number of remote nodes.

doc/source/introduction/consuming.rst

@@ -0,0 +1,58 @@
+===================
+Consuming StarlingX
+===================
+
+StarlingX is ready for you to use today. However limitations exist
+regarding what you can do with the
+open source software. Features of the software
+like Secure Boot and live Software Update are not fully enabled by
+the community.
+
+The community does not provide signed software images, which are needed
+to enable features that depend
+on signed images to implement Security features.
+Providing signed images typically are the responsibility of
+commercial vendors or the users themselves.
+As such, the following are
+three ways in which you can consume StarlingX.
+
+Deploy the open source code
+---------------------------
+
+You can use the open source software directly. Our community partner
+CENGN has an archive containing ready to run
+ISO images of the current StarlingX releases and daily builds.
+
+As previously mentioned, these images are not signed
+and thus do not support Secure Boot or live Software Updates. You can also
+build your own images of course.
+
+The StarlingX community recommends that anyone looking to deploy
+the open source software use the release images, which have been
+tested and validated by the community. Developers
+looking to work against the tip of the source trees would
+typcally use the daily builds.
+
+Deploy an internal version of StarlingX
+---------------------------------------
+
+If you are part of a company, the company itself can create
+a team to create their own version of
+StarlingX for the company. Such a team could do
+acceptance testing of the open source software, customize it as
+needed, sign their own internal images, and use the features
+in StarlingX to enable Secure Boot and to develop and deliver live
+Software Updates (patches) to their internal users.
+
+Deploy code from a vendor
+-------------------------
+
+You can also consume a commercial vendor's StarlingX-based
+product or solution. Vendors can provide signed images and
+signed Software Updates. They can add features or content to
+the open source software. They may provide other services such
+as technical support.
+
+The StarlingX community
+expects several vendors to provide StarlingX-based products
+and solutions. We hope to see more as our community grows.

doc/source/introduction/index.rst

@@ -2,23 +2,19 @@
 StarlingX Introduction
 ======================
 
-StarlingX encompasses many areas.
+This is the place to start learning about StartlingX!
-The information in this section introduces you to StarlingX,
-describes how various users use StarlingX, how StarlingX
-behaves "out of the box", how software evaluation occurs, and
-a roadmap of the documentation.
-
-Following are the introductory topics available for StarlingX:
 
 .. toctree::
    :maxdepth: 1
 
    /introduction/intro
+   /introduction/consuming
+   /introduction/concepts
+   /introduction/roadmap
    /introduction/kubernetes
    /introduction/openstack
    /introduction/box
    /introduction/software_evaluation
-   /introduction/roadmap
 
 
 

doc/source/introduction/intro.rst

@@ -2,7 +2,28 @@
 Project introduction
 ====================
 
-This topic is coming soon.
+Welcome to the StarlingX project!
 
-`Linked Story <https://storyboard.openstack.org/#!/story/2005002>`__
+StarlingX is a fully integrated Edge Cloud software stack that includes
+everything that you need to deploy an Edge Cloud on one server,
+two servers, or up to 100 servers.
 
+StarlingX includes an operating
+system, storage and networking components, and all of the Cloud
+Infrastructure needed to run Edge workloads in one
+easy to install package.
+
+All of the software has
+been tuned and optimized to meet Edge application requirements.
+
+The stack pre-defines
+several different configurations that are designed to meet a variety of
+Edge Cloud deployment needs.
+
+The StarlingX project's goal is to make the task of deploying and managing
+a high performance Edge Cloud as simple as possible.
+
+The StarlingX Documentation consists of number of sections. The
+other documents in this Introduction section will help you learn some
+of the basic concepts of StarlingX and how to find more detailed
+information on the software.

doc/source/introduction/roadmap.rst

@@ -1,6 +1,6 @@
-=====================
+===========
-Documentation roadmap
+Doc roadmap
-=====================
+===========
 
 This topic is coming soon.