services guide and overall docs update part 1

Signed-off-by: Phil Prasek <prasek@gmail.com>

docs/README.md

@@ -1,20 +1,140 @@
-# Crossplane
+# Welcome to Crossplane!
 
-Crossplane is an open source multicloud control plane. It introduces workload and resource abstractions on-top of existing managed services that enables a high degree of workload portability across cloud providers. A single crossplane enables the provisioning and full-lifecycle management of services and infrastructure across a wide range of providers, offerings, vendors, regions, and clusters. Crossplane offers a universal API for cloud computing, a workload scheduler, and a set of smart controllers that can automate work across clouds.
+Crossplane is an open source multicloud control plane to manage your
+cloud-native applications and infrastructure across environments, clusters,
+regions and clouds. It enables provisioning and full-lifecycle management
+ of applications and managed services from your choice of cloud using `kubectl`.
 
-<h4 align="center"><img src="media/arch.png" alt="Crossplane" height="400"></h4>
+Crossplane can be installed into an existing Kubernetes cluster to add managed
+service provisioning or deployed as a dedicated control plane for multi-cluster
+management and workload scheduling.
 
-Crossplane presents a declarative management style API that covers a wide range of portable abstractions including databases, message queues, buckets, data pipelines, serverless, clusters, and many more coming. It’s based on the declarative resource model of the popular [Kubernetes](https://github.com/kubernetes/kubernetes) project, and applies many of the lessons learned in container orchestration to multicloud workload and resource orchestration.
+Crossplane enables the community to build and publish Stacks to add more clouds
+and cloud services to Crossplane with support for out-of-tree extensibility and
+independent release schedules. Crossplane includes Stacks for [GCP][stack-gcp], 
+[AWS][stack-aws], and [Azure][stack-azure] today.
 
-Crossplane supports a clean separation of concerns between developers and administrators. Developers define workloads without having to worry about implementation details, environment constraints, and policies. Administrators can define environment specifics, and policies. The separation of concern leads to a higher degree of reusability and reduces complexity.
+<h4 align="center"><img src="media/crossplane-overview.png" alt="Crossplane"
+height="400"></h4>
 
-Crossplane includes a workload scheduler that can factor a number of criteria including capabilities, availability, reliability, cost, regions, and performance while deploying workloads and their resources. The scheduler works alongside specialized resource controllers to ensure policies set by administrators are honored.
+Crossplane has four main feature areas that can be used independently:
+1. Crossplane Services - provision managed services from kubectl.
+1. Crossplane Stacks - extend Crossplane with new functionality.
+1. Crossplane Workloads - define complete applications and schedule across
+   clusters, regions, and clouds.
+1. Crossplane Clusters - manage multiple Kubernetes clusters from a single
+   control plane.
+
+## Crossplane Services 
+Crossplane Services supports managed service provisioning
+using `kubectl`. It applies the Kubernetes pattern for Persistent Volume (PV)
+claims and classes to managed service provisioning with support for a strong
+separation of concern between app teams and cluster administrators. 
+
+App teams can choose between cloud-specific and portable services including
+managed databases, message queues, buckets, data pipelines, and more to define
+complete applications, build once, and deploy into multiple clouds using
+continuous delivery pipelines or GitOps flows. 
+
+Cluster administrators can define self-service policies and best-practice
+configurations to accelerate app delivery and improve security, so app teams can
+focus on delivering their app instead of cloud-specific infrastructure details.
+
+The [Crossplane Services Guide][services-user-guide] explores related concepts and
+shows how to use Crossplane Services to deploy a Wordpress instance that
+securely consumes a managed `MySQLInstance` from GCP, AWS, or Azure from
+`kubectl`.
+
+## Crossplane Stacks
+Stacks extend Crossplane with new functionality and can be
+installed using the [Stack
+Manager][stacks-manager]
+via the [Kubernetes
+API][stack-install-docs]
+or with the [crossplane kubectl
+plugin][crossplane-cli] [`stack install`][crossplane-cli-usage] command.
+
+Crossplane is built on the Kubernetes API machinery as a platform, and Stacks
+simplify extending the Kubernetes API to provision and lifecycle manage apps and
+the managed service infrastructure they depend on, including [Stack security and
+isolation][stack-security-design].
+
+The [Crossplane Stacks Guide][stack-user-guide] shows how to deploy a portable [Wordpress Stack][stack-wordpress-registry]
+into multiple clouds using Infra Stacks including
+[stack-gcp][stack-gcp], [stack-aws][stack-aws], and [stack-azure][stack-azure].
+
+### Infrastructure Stacks 
+Infra Stacks like [stack-gcp][stack-gcp], [stack-aws][stack-aws], and [stack-azure][stack-azure] 
+extend the Kubernetes API to support managed service provisioning (DBaaS, cache, buckets), secure
+connectivity (VPCs, subnets, peering, ACLs, secrets), and provisioning managed
+Kubernetes clusters on demand to further isolate the blast radius of applications. 
+
+Infra Stacks are pre-built and published to the [Stacks
+registry][stack-registry] where they can
+be installed by a Cluster Admin using a
+[`ClusterStackInstall`][stack-install-docs]
+Kubernetes API kind or with the [`stack
+install`][crossplane-cli-usage] command that
+installs a Stacks with permissions to watch resources at a cluster level, across
+all namespaces.
+
+Infra Stacks are covered in both the [Crossplane Services
+Guide][services-user-guide] and the
+[Crossplane Stacks Guide][stack-user-guide].
+
+### Application Stacks 
+App Stacks depend on Infra Stacks like
+[stack-gcp][stack-gcp], [stack-aws][stack-aws], and [stack-azure][stack-azure]
+to provide managed services via the Kubernetes API.
+
+App Stacks are pre-built and published to the [Stacks
+registry][stack-registry] where they can
+be installed by an app team using a
+[`StackInstall`][stack-install-docs]
+Kubernetes API kind or with the [`stack
+install`][crossplane-cli-usage] command that
+installs Stacks with permissions only within a single namespace.
+
+The [Crossplane Stacks Guide][stack-user-guide] covers how to deploy a portable 
+[Wordpress Stack][stack-wordpress] into multiple clouds using Infra Stacks such
+as [stack-gcp][stack-gcp], [stack-aws][stack-aws], and [stack-azure][stack-azure].
+
+### Build your own Stack 
+The [Crossplane Developer Guide][stack-developer-guide] shows how to
+build and extend Infra Stacks and App Stacks. 
+
+## Crossplane Workloads 
+Crossplane includes an extensible workload scheduler that observes application 
+policies to select a suitable target cluster from a pool of available clusters. 
+The workload scheduler can be customized to consider a number of criteria including 
+capabilities, availability, reliability, cost, regions, and performance while 
+deploying workloads and their resources.
+
+Complex workloads can be modeled as a
+[`KubernetesApplication`][k8s-app-design]
+resource as done by the portable [Wordpress Stack][stack-wordpress] which
+automates the lifecycle of a
+[`KubernetesApplication`][k8s-app-design]
+including provisioning and secure connectivity to a managed `MySQLInstance`.
+
+## Crossplane Clusters 
+Crossplane supports dynamic provisioning of managed
+Kubernetes clusters from a single control plane with consistent multi-cluster
+best-practice configuration and secure connectivity between target Kubernetes
+clusters and the managed services provisioned for applications. Managed
+Kubernetes clusters can be dynamically provisioned with a `KubernetesCluster`
+resource as done by the portable [Wordpress Stack][stack-wordpress] which
+automates the lifecycle of a `KubernetesCluster`.
 
 ## Architecture and Vision
 
-The full architecture and vision of the Crossplane project is described in depth in the [architecture document](https://docs.google.com/document/d/1whncqdUeU2cATGEJhHvzXWC9xdK29Er45NJeoemxebo/edit?usp=sharing). It is the best place to learn more about how Crossplane fits into the Kubernetes ecosystem, the intended use cases, and comparisons to existing projects.
+The full architecture and vision of the Crossplane project is described in depth
+in the [architecture document][arch-doc].
+It is the best place to learn more about how Crossplane fits into the Kubernetes
+ecosystem, the intended use cases, and comparisons to existing projects.
 
-## Table of Contents
+## Learn More
+If you have any questions, please drop us a note on [Crossplane Slack][join-crossplane-slack] or [contact us][contact-us]!
 
 * [Quick Start Guide](quick-start.md)
 * [Getting Started](getting-started.md)
@@ -24,5 +144,42 @@ The full architecture and vision of the Crossplane project is described in depth
   * [Running Resources](running-resources.md)
   * [Troubleshooting](troubleshoot.md)
 * [Concepts](concepts.md)
+* [API Reference](api.md)
 * [FAQs](faqs.md)
 * [Contributing](contributing.md)
+
+### Next Steps
+Use [stack-gcp][stack-gcp], [stack-aws][stack-aws], and [stack-azure][stack-azure] in the the following guides:
+* [Crossplane Service Guide][services-user-guide] - upgrade an existing Kubernetes cluster
+  to support managed service provisioning from kubectl.
+* [Crossplane Stacks Guide][stack-user-guide] - deploy a portable Wordpress Stack into
+  multiple clouds.
+
+[Learn more][learn-more] about Crossplane.
+
+<!-- Named links -->
+[services-user-guide]: services-guide.md
+[stack-user-guide]: stacks-guide.md
+[stack-developer-guide]: developer-guide.md
+[stack-manager]: https://github.com/crossplaneio/crossplane/blob/master/design/design-doc-stacks.md#terminology
+[crossplane-cli]: https://github.com/crossplaneio/crossplane-cli
+[crossplane-cli-usage]: https://github.com/crossplaneio/crossplane-cli#usage
+[stack-sercurity-design]: https://github.com/crossplaneio/crossplane/blob/master/design/one-pager-stacks-security-isolation.md
+
+[stack-wordpress-registry]: https://hub.docker.com/r/crossplane/sample-stack-wordpress
+[stack-wordpress]: https://github.com/crossplaneio/sample-stack-wordpress
+
+[stack-gcp]: https://github.com/crossplaneio/stack-gcp
+[stack-aws]: https://github.com/crossplaneio/stack-aws
+[stack-azure]: https://github.com/crossplaneio/stack-azure
+[stack-registry]: https://hub.docker.com/search?q=crossplane&type=image
+[stack-install-docs]: https://github.com/crossplaneio/crossplane/blob/master/design/design-doc-stacks.md#installation-flow
+
+[k8s-app-design]: https://github.com/crossplaneio/crossplane/blob/master/design/design-doc-complex-workloads.md#design
+
+[arch-doc]: https://docs.google.com/document/d/1whncqdUeU2cATGEJhHvzXWC9xdK29Er45NJeoemxebo/edit?usp=sharing
+
+[contact-us]: https://github.com/crossplaneio/crossplane#contact
+[join-crossplane-slack]: https://slack.crossplane.io
+[learn-more]: learn-more.md
+

docs/cloud-providers.md

@@ -1,7 +1,7 @@
 ---
 title: Adding Your Cloud Providers
 toc: true
-weight: 330
+weight: 230
 indent: true
 ---
 

docs/concepts.md

@@ -1,7 +1,7 @@
 ---
 title: Concepts
 toc: true
-weight: 410
+weight: 1510
 ---
 # Concepts
 

docs/contributing.md

@@ -1,11 +1,11 @@
 ---
 title: Contributing
 toc: true
-weight: 710
+weight: 5110
 ---
 # Contributing
 
 Crossplane is a community driven project and we welcome contributions.
 That includes [opening issues](https://github.com/crossplaneio/crossplane/issues) for improvements you'd like to see as well as submitting changes to the code base.
 
-For more information about the contribution process, please see the [contribution guide](https://github.com/crossplaneio/crossplane/blob/master/CONTRIBUTING.md).
+For more information about the contribution process, please see the [contribution guide](https://github.com/crossplaneio/crossplane/blob/master/CONTRIBUTING.md).

docs/deploy.md

@@ -1,7 +1,7 @@
 ---
 title: Deploying Workloads
 toc: true
-weight: 340
+weight: 240
 indent: true
 ---
 # Deploying Workloads

docs/developer-guide.md

@@ -0,0 +1,105 @@
+---
+title: Developer Guide
+toc: true
+weight: 5010
+---
+# Developer Guide
+Welcome to the Crossplane Developer Guide!
+
+## Overview 
+Infra Stacks like
+[stack-gcp][stack-gcp], [stack-aws][stack-aws], and [stack-azure][stack-azure] extend Crossplane
+to support managed service provisioning (databases, caches, buckets), secure
+connectivity (VPCs, subnets, peering, ACLs, secrets), and provisioning managed
+Kubernetes clusters on demand to further isolate the blast radius of
+applications. 
+
+Infra Stacks are typically pre-built and published to the [Stacks
+registry][stack-registry], where they can
+be installed by a cluster administrator using a
+[`ClusterStackInstall`][stack-install-docs]
+kind via the Kubernetes API or with the [`stack
+install`][crossplane-cli-usage] command.
+
+App Stacks depend on Infra Stacks like
+[stack-gcp][stack-gcp], [stack-aws][stack-aws], or [stack-azure][stack-azure]
+ to provide the managed services they depend on via the Kubernetes API.
+
+App Stacks may also be pre-built and published to the [Stacks
+registry][stack-registry] where they can
+be deployed by application teams using a
+[`StackInstall`][crossplane-cli-usage]]
+kind via the Kubernetes API or with the [`stack
+install`][crossplane-cli-usage]) command.
+
+## Infra Stacks 
+### Using Infra Stacks 
+The [Crossplane Services Guide][services-user-guide]
+ shows how to use existing Infra Stacks to deploy a Wordpress `Deployment`
+that securely consumes a MySQL instance from GCP, AWS, or Azure all from
+`kubectl`. 
+
+### Building Infra Stacks
+Infra Stacks are out-of-tree Crossplane extensions
+that can be built and published on their own schedule separate from the core
+Crossplane repos.
+
+Crossplane enables the community to build a modular, open cloud control plane
+where any cloud service or capability can be added using the [Stack
+Manager][stack-manager],
+an extension manager for the Kubernetes API. Crossplane Stacks simplify the work
+required to build, publish, install and manage control plane extensions with a
+powerful RBAC permission model, integrated dependency management, and more.
+
+The [Infra Stack Developer Guide][infra-stack-developer-guide] shows how to:
+* Extend existing Infra Stacks ([stack-gcp][stack-gcp], [stack-aws][stack-aws], 
+[stack-azure][stack-azure]) to add more cloud services.
+* Build a new Infra Stack to add more cloud providers.
+* Make independent cloud offerings available via the Kubernetes API, so
+  application teams can use them just like standard Kubernetes resources.
+
+## App Stacks
+### Using App Stacks 
+The [Crossplane Stacks Guide][stacks-user-guide] guide
+shows how to use a [portable App
+Stack][stack-wordpress-registry] that can
+deploy with any Infra Stack including: 
+[stack-gcp][stack-gcp], [stack-aws][stack-aws], or [stack-azure][stack-azure].
+
+### Building App Stacks
+To learn how to build a "Hello World" Stack see the
+[Stacks Quick Start][stacks-quick-start].
+
+For a complete App Stack, see the [portable Wordpress App
+Stack][stack-wordpress] with a
+kubebuilder-based app
+[`Controller`][kubernetes-controller]
+that owns a `WordressInstance` CRD, builds a complete `KubernetesApplication`,
+and automates much of what's covered in the [Crossplane Services
+Guide][services-user-guide] plus dynamic cluster provisioning, so you can 
+provision a complete Wordpress app instance from `kubectl` using a single Kubernetes object.
+
+
+## Learn More
+If you have any questions, please drop us a note on [Crossplane Slack][join-crossplane-slack] or [contact us][contact-us]!
+
+To [learn more][learn-more] checkout these [useful links][learn-more].
+
+<!-- Named links -->
+[services-user-guide]: services-guide.md
+[stack-user-guide]: stacks-guide.md
+[stack-registry]: https://hub.docker.com/search?q=crossplane&type=image
+[crossplane-cli-usage]: https://github.com/crossplaneio/crossplane-cli#usage
+[stack-install-docs]: https://github.com/crossplaneio/crossplane/blob/master/design/design-doc-stacks.md#installation-flow
+[stack-gcp]: https://github.com/crossplaneio/stack-gcp
+[stack-aws]: https://github.com/crossplaneio/stack-aws
+[stack-azure]: https://github.com/crossplaneio/stack-azure
+[stack-wordpress]: https://github.com/crossplaneio/sample-stack-wordpress
+[stack-wordpress-registry]: https://hub.docker.com/r/crossplane/sample-stack-wordpress
+[stack-manager]: https://github.com/crossplaneio/crossplane/blob/master/design/design-doc-stacks.md#terminology
+[infra-stack-developer-guide]: developer-guide.md
+[stack-quick-start]: https://github.com/crossplaneio/crossplane-cli#quick-start-stacks
+[kubernetes-controller]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#custom-controllers
+[join-crossplane-slack]: https://slack.crossplane.io
+[contact-us]: https://github.com/crossplaneio/crossplane#contact
+[learn-more]: learn-more.md

docs/faqs.md

@@ -1,7 +1,7 @@
 ---
 title: FAQs
 toc: true
-weight: 610
+weight: 2110
 ---
 # Frequently Asked Questions (FAQs)
 

docs/install-crossplane.md

@@ -1,7 +1,7 @@
 ---
 title: Install
 toc: true
-weight: 320
+weight: 220
 indent: true
 ---
 # Installing Crossplane

docs/learn-more.md

@@ -1,10 +1,12 @@
 ---
 title: Learn More
 toc: true
-weight: 810
+weight: 6010
 ---
 # Learn More
 
+If you have any questions, please drop us a note on [Crossplane Slack][join-crossplane-slack] or [contact us][contact-us]!
+
 ***Learn more about using Crossplane***
  - [GitLab deploys into multiple clouds from kubectl using Crossplane](https://about.gitlab.com/2019/05/20/gitlab-first-deployed-kubernetes-api-to-multiple-clouds/)
  - [CNCF Talks & Community Presentations](https://www.youtube.com/playlist?list=PL510POnNVaaZJj9OG6PbgsZvgYbhwJRyE)
@@ -29,3 +31,6 @@ weight: 810
 - Drop us a note on Twitter: [@crossplane_io](https://twitter.com/crossplane_io)
 - Email us: [info@crossplane.io](mailto:info@crossplane.io)
 
+<!-- Named links -->
+[join-crossplane-slack]: https://slack.crossplane.io
+[contact-us]: https://github.com/crossplaneio/crossplane#contact