aligned .md files with GitBook
Change-Id: I932736839a25bf43637469bd7b7eade1ad5d8daf
diff --git a/README.md b/README.md
index 78c4505..f3c628a 100644
--- a/README.md
+++ b/README.md
@@ -1,60 +1,20 @@
-# Welcome to CORD
+# Building and Installing CORD
-This repository is an entry point to CORD's open reference
-implementation. It helps you to build and deploy CORD.
+This is the main entry point for building and installing CORD.
+If this is your first encounter with CORD, we suggest you start by
+bringing up an emulated version called CORD-in-a-Box.
+It installs CORD on a set of virtual machines running on a single
+physical server. Just follow our [CORD-in-a-Box Guide](docs/quickstart.md).
-### What is CORD
+You can also install CORD on a physical POD. This involves first assembling
+a set of servers and switches, and then pointing the build system at
+that target hardware. Just follow our
+[Physical POD Guide](docs/quickstart_physical.md).
-CORD (Central Office Re-architected as a Datacenter) is a
-revolutionary concept to turn Telco Central Offices (and MSO Head
-Ends) into a modern mini-datacenters. We call this a CORD POD. A
-POD is made up of commodity servers, switches, and other networking
-devices. The POD is an application deployment platform optimized for
-both conventional cloud-scale applications as well as virtual network
-functions (VNF).
-
-### What is the CORD Reference Implementation
-
-The CORD open reference implementation is comprised of:
-
-- A number of POD hardware specifications that can serve as reference
- implementations
-
-- A software platform that when deployed on the servers implements
- service-agnostic software infrastructure enabling deployment of
- sophisticated network services
-
-- A few sample service implementations that can be readily deployed
- onto CORD PODs
-
-- A deployment automation framework that simplifies the installation
- of the platform layers as well as the sample services
-
-- An extendable test framework and test suite to verify and
- characterize the platfrom as well as the sample services
-
-- Extensive documentation to work with CORD
-
-### Quick Start
-
-If this is your first encounter with CORD, you may consider giving it
-a quick spin. We made it real easy. You can bring up CORD on a single
-server or on a few servers (with or without a real fabric) with a few
-commands.
-
-Please follow our [Quick Start Tutorial](docs/quickstart.md).
-
-
-### Further Topics
-
-* POD Reference Designs [coming]
-* CORD Software Architecure [coming]
-* Customizing CORD [coming]
-
-
-### References
+For additional information about the CORD Project, see:
* [Project Home](http://opencord.org)
+* [Wiki](http://wiki.opencord.org)
* [Jira](http://jira.opencord.org)
* [Gerrit](http://gerrit.opencord.org)
diff --git a/SUMMARY.md b/SUMMARY.md
new file mode 100644
index 0000000..bccca5a
--- /dev/null
+++ b/SUMMARY.md
@@ -0,0 +1,6 @@
+# Summary
+
+* [Building CORD](README.md)
+ * [CORD-in-a-Box](docs/quickstart.md)
+ * [Physical POD](docs/quickstart_physical.md)
+
diff --git a/docs/OFFLINE_INSTALL.md b/docs/OFFLINE_INSTALL.md
index 641c0c6..0813615 100644
--- a/docs/OFFLINE_INSTALL.md
+++ b/docs/OFFLINE_INSTALL.md
@@ -1,4 +1,8 @@
# Offline (local repository) CORD Install
+
+[*This document is out-of-date. It contains helpful suggestions about how one
+might do an offline install, but it is not current with the latest CORD release.*]
+
It is possible to install CORD using a local Ubuntu application
repository. This can be useful for several use cases including
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 0cb6ee1..e7ccc91 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,18 +1,19 @@
-# CORD-in-a-Box Quick Start Guide
+# CORD-in-a-Box: Quick Start Guide
-This tutorial guide walks through the steps to bring up a demonstration CORD
+This guide walks through the steps to bring up a demonstration CORD
"POD", running in virtual machines on a single physical server (a.k.a.
"CORD-in-a-Box"). The purpose of this demonstration POD is to enable those
interested in understanding how CORD works to examine and interact with a
running CORD environment. It is a good place for novice CORD users to start.
-**NOTE:** *This tutorial installs a simplified version of a CORD POD on a
+**NOTE:** *This guide describes how to install
+a simplified version of a CORD POD on a
single server using virtual machines. If you are looking for instructions on
-how to install a multi-node POD, you will find them in
-[quickstart_physical.md](./quickstart_physical.md). For more details about the
+how to install a multi-node POD, you will find them in the
+[Physical POD Guide](./quickstart_physical.md). For more details about the
actual build process, look there.*
-## What you need (Prerequisites)
+## What You Need (Prerequisites)
You will need a *target server*, which will run both a development environment
in a Vagrant VM (used to deploy CORD) as well as CORD-in-a-Box itself.
@@ -162,7 +163,7 @@
The CORD build environment is located in `/cord/build` inside this VM. It is
possible to manually run individual steps in the build process here if you
-wish; see [quickstart_physical.md](./quickstart_physical.md) for more
+wish; see the [Physical POD Guide](./quickstart_physical.md) for more
information on how to run build steps.
### prod VM
@@ -347,7 +348,7 @@
More information on using Kibana can be be found [in its
documentation](https://www.elastic.co/guide/en/kibana/current/index.html).
-## Test results
+## Test Results
After CORD-in-a-Box was set up, a couple of basic health
tests were executed on the platform. The results of these tests can be
@@ -476,6 +477,6 @@
CORD POD.
You are now ready to bring up a multi-node POD with a real switching fabric and
-multiple physical compute nodes. The process for doing so is described in
-[quickstart_physical.md](./quickstart_physical.md).
+multiple physical compute nodes. The process for doing so is
+described in the [Physical POD Guide](./quickstart_physical.md).
diff --git a/docs/quickstart_physical.md b/docs/quickstart_physical.md
index 63b4046..7e24350 100644
--- a/docs/quickstart_physical.md
+++ b/docs/quickstart_physical.md
@@ -1,4 +1,4 @@
-# CORD Quick Start Guide using Physical Nodes
+# Physical POD: Quick Start Guide
This guide is meant to enable the user to utilize the artifacts of this
repository to to deploy CORD on to a physical hardware rack. The artifacts in
@@ -7,9 +7,9 @@
**NOTE:** *If you are new to CORD, you should start by bringing up a development
POD on a single physical server to get familiar with the CORD deployment
-process. Instructions to do so are in [quickstart.md](./quickstart.md).*
+process. Instructions to do so can be found [here](./quickstart.md).*
-## Physical configuration
+## Physical Configuration
As depicted in the diagram above the base model for the CORD POD deployment
diff --git a/docs/quickstart_vm.md b/docs/quickstart_vm.md
index 6a89f0a..e60ad7c 100644
--- a/docs/quickstart_vm.md
+++ b/docs/quickstart_vm.md
@@ -1,9 +1,7 @@
# CORD Quick Start Guide using Virtual Machine Nodes
-[*This description is for bringing up a CORD POD on virtual
-machines on a single physical host. The purpose of this solution
-is to give the user an experience of bring up a CORD on bare
-metal.*]
+[*This tutortial is obsolete. Instead see information about CORD-in-a-Box,
+as outlined in the [Quick Start Tutorial](quickstart.md).*]
This guide is meant to enable the user to quickly exercise the capabilities
provided by the artifacts of this repository. There are three high level tasks