docs(*): improve grammar and fix typos

Author: mboersma

src/index.md

@@ -1,8 +1,10 @@
 # Welcome to Deis Workflow
 
-Deis (pronounced DAY-iss) Workflow is an open source Platform as a Service (PaaS) that adds a developer-friendly layer to any Kubernetes cluster, making it easy to deploy and manage applications on your own servers.  It includes capabilities for building and deploying from source via git push, configuring your applications, managing and rolling back releases, managing application domain names and SSL certificates, edge routing, application log aggregation, and managing access to application resources.  All of this is exposed through a simple REST API and command line interface.
+Deis (pronounced DAY-iss) Workflow is an open source Platform as a Service (PaaS) that adds a developer-friendly layer to any Kubernetes cluster, making it easy to deploy and manage applications on your own servers.
 
-For more detailed information about Workflow view the [Concepts][concepts] and [Architecture][arch] sections.
+Workflow includes capabilities for building and deploying from source via `git push`, configuring your applications, creating and rolling back releases, managing application domain names and SSL certificates, providing edge routing, aggregating application logs, and controlling access to application resources.  All of this is exposed through a simple REST API and command line interface.
+
+For more detailed information about Workflow, view the [Concepts][concepts] and [Architecture][arch] sections.
 
 To get started with Workflow, follow our [Quick Start][quickstart] guide.
 

src/installing-workflow/installing-deis-workflow.md

@@ -4,16 +4,15 @@ We will use the Helm package manager for Kubernetes to install Deis Workflow ont
 
 ## Check Your Setup
 
-First check that you have `helm` installed and the version is correct.
+First check that the `helm` command is available and the version is 0.6 or newer.
 
 ```
 $ helm --version
-0.4.0
+helm version 0.6.0+1c8688e
 ```
 
-Ensure your kubectl client is installed and ensure it can connect to your Kubernetes cluster. This
-is where Helm will attempt to communicate with the cluster. You can test that it is working
-properly by running:
+Ensure the `kubectl` client is installed and can connect to your Kubernetes cluster. `helm` will
+use it to communicate. You can test that it is working properly by running:
 
 ```
 $ helm target
@@ -25,7 +24,7 @@ Grafana is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/ser
 InfluxDB is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/monitoring-influxdb
 ```
 
-If you see a list of targets like the one above, 'helm' can communicate with the kubernetes master.
+If you see a list of targets like the one above, `helm` can communicate with the Kubernetes master.
 
 Deis Workflow requires Kubernetes 1.2 or higher. You can test that by running:
 

src/installing-workflow/quickstart.md

@@ -4,7 +4,7 @@ These steps will help you install and configure Deis Workflow on a Kubernetes cl
 
 ## Check System Requirements
 
-Please refer to the prerequisites and [system requirements][] for considerations when planning your Kubernetes environment.
+Please refer to the [system requirements][] for considerations when planning your Kubernetes environment.
 
 ## Choose a Provider
 

src/installing-workflow/system-requirements.md

@@ -22,13 +22,9 @@ Deis workflow has been tested with the Kubernetes v1.2 release line. It is incom
 
 # Docker Requirements
 
-## Docker Version
-
-Any Kubernetes 1.1 cluster should also use a Docker version < 1.10.0 so that `kubectl exec` and Deis database health checks work properly (Refs: [fsouza/go-dockerclient#455](https://github.com/fsouza/go-dockerclient/issues/455) and [kubernetes/kubernetes#19720](https://github.com/kubernetes/kubernetes/issues/19720)).
-
 ## Docker Insecure Registry
 
-The on-cluster, Deis-managed Docker registry is not deployed with TLS by default. As such, all Kubernetes worker nodes must have their Docker daemons configured to use an insecure registry. The subnet should encompass any private networks used by your worker nodes including any overlay networks. Depending on your Kubernetes and Docker configuration, setting `EXTRA_DOCKER_OPTS="--insecure-registry=10.0.0.0/8"` may be sufficient.
+The on-cluster, Deis-managed Docker registry is not deployed with TLS by default. As such, all Kubernetes worker nodes must have their Docker daemons configured to use an insecure registry. The subnet should encompass any private networks used by your worker nodes, including any overlay networks. Depending on your Kubernetes and Docker configuration, setting `EXTRA_DOCKER_OPTS="--insecure-registry=10.0.0.0/8"` may be sufficient.
 
 ## SELinux + OverlayFS
 

src/understanding-workflow/concepts.md

@@ -8,8 +8,8 @@ Twelve-Factor apps as containers across a Kubernetes cluster.
 The [Twelve-Factor App][] is a methodology for building modern
 applications that can be scaled across a distributed system.
 
-We consider it an invaluable synthesis of much experience with
-software-as-a-service apps in the wild, especially on the
+Twelve-factor is a valuable synthesis of years of experience with
+software-as-a-service apps in the wild, particularly on the
 Heroku platform.
 
 Workflow is designed to run applications that adhere to the [Twelve-Factor App][]
@@ -23,14 +23,15 @@ the activity on your cluster, including: desired state convergence, stable
 service addresses, health monitoring, service discovery, and DNS resolution.
 
 Workflow builds upon Kubernetes abstractions like Services, Replication
-Controllers and Pods to provide a developer-friendly UX, source to image, log
-aggregation, etc.
+Controllers, and Pods to provide a developer-friendly experience. Building containers
+directly from application source code, aggregating logs, and managing deployment
+configurations and app releases are just some of the features Workflow adds.
 
-Workflow is shipped as a Kubernetes-native application, installable via
-[Helm][helm], so operators familiar with Kubernetes will feel right at home
-running Workflow.
+Deis Workflow is a set of Kubernetes-native components, installable via
+[Helm][helm]. Systems engineers who are familiar with Kubernetes will feel right
+at home running Workflow.
 
-For a detailed overview of Workflow components, see our [component][components] break down.
+See the [components][components] overview for more detail.
 
 ## Docker
 
@@ -46,23 +47,23 @@ Applications which are packaged via a buildpack are run in Docker containers as
 part of the `slugrunner` process. View the [slugrunner component][slugrunner]
 for more information.
 
-Applications which use either a Dockerfile or reference an external Docker
-Image are launched unmodified.
+Applications which use either a Dockerfile or reference external Docker
+images are launched unmodified.
 
 ## Applications
 
 Workflow is designed around the concept of an [application][], or app.
 
-Applications can come in three forms:
+Applications come in one of three forms:
 
-1. as collection of source files stored in a Git repository
-2. as a Dockerfile, which describes how to build your app
-3. a reference to an already built Docker Image, hosted on a remote Docker repository
+1. a collection of source files stored in a `git` repository
+2. a Dockerfile and associated source files stored in a `git` repository
+3. a reference to an existing image at a Docker repository
 
-Applications identified by a unique name for easy reference. If you do not
-specify a name when creating your application Workflow generates one for you.
-Workflow also tracks other related information for your application including
-any domain names, SSL Certificates and developer provided configuration.
+Applications are identified by a unique name for easy reference. If you do not
+specify a name when creating your application, Workflow generates one for you.
+Workflow also manages related information, including domain names, SSL
+certificates, and developer-provided configuration.
 
 ## Build, Release, Run
 
@@ -73,33 +74,32 @@ any domain names, SSL Certificates and developer provided configuration.
 The [builder][] component processes incoming `git push deis master` requests
 and manages your application packaging.
 
-If your application is using a [buildpack][buildpacks] builder will launch an ephemeral
+If your application is using a [buildpack][buildpacks], builder will launch an ephemeral
 job to extract and execute the packaging instructions. The resulting
 application artifact is stored by the platform for execution during the run
 stage.
 
-If instead, you provide a [Dockerfile][dockerfile] builder will use the
-instructions you have provided to build a Docker Image. The resulting artifact is
-stored in a Deis-managed registry which will be referenced during the run
-stage.
+If instead builder finds a [Dockerfile][dockerfile], it follows those instructions to
+create a Docker image. The resulting artifact is stored in a Deis-managed registry which
+will be referenced during the run stage.
 
-If you already have an external system building your application container you
-can simply reference that artifact. When using [external Docker
-images][dockerimage] the builder component doesn't attempt to repackage your
+If another system already builds and packages your application, that container
+artifact can be used directly. When referencing an [external Docker
+image][dockerimage], the builder component doesn't attempt to repackage your
 app.
 
 ### Release Stage
 
 During the release stage, a [build][] is combined with [application configuration][config]
-to create a new numbered [release][]. New releases are created any time a new
-build is created or application configuration is changed. Tracking releases
-makes it easy to rollback to any previous release.
+to create a new, numbered [release][]. New releases are created any time a new
+build is created or application configuration is changed. Tracking releases as a
+"write-only ledger" this way makes it easy to rollback to any previous release.
 
 ### Run Stage
 
-The run stage is responsible for deploying the new release to the underlying
-Kubernetes cluster. The run stage launches a new Replication Controller which
-references the new release. By managing the desired replica count, Workflow
+The run stage deploys the new release to the underlying Kubernetes cluster by
+launching a new Replication Controller which references the new release.
+By managing the desired replica count, Workflow
 orchestrates a zero-downtime, rolling update of your application. Once
 successfully updated, Workflow removes the last reference to the old release.
 Note that during the deploy, your application will be running in a mixed mode.
@@ -108,11 +108,11 @@ Note that during the deploy, your application will be running in a mixed mode.
 
 Workflow treats all persistent services such as databases, caches, storage,
 messaging systems, and other [backing services][] as resources managed
-separtely from your application. This philosophy aligns with Twelve-Factor
+separately from your application. This philosophy aligns with Twelve-Factor
 best practices.
 
-Applications are attached to backing services using [environment variables][].
-Because applications are decoupled from backing services, apps are free to
+Applications attach to backing services using [environment variables][].
+Because apps are decoupled from backing services, they are free to
 scale up independently, to use services provided by other apps, or to switch
 to external or third-party vendor services.