Merge pull request #671 from garden-io/documentation-review

docs: fixes and updates

README.md

@@ -14,9 +14,9 @@ With the Stack Graph, each part of your stack can _describe itself_ using simple
 
 ## Key features
 
-- Spin up your whole stack with a single command, and (optionally) watch for changes. Because of the Stack Graph, only what's needed gets re-built, re-deployed, and/or re-tested, so you get **much faster feedback loops**.
+- Spin up your whole stack with a single command, and (optionally) watch for changes. Because of the Stack Graph, only what's needed gets re-built, re-deployed, and/or re-tested, so you get a **much faster feedback loop**.
 - Easily write [integration test suites](https://docs.garden.io/using-garden/features-and-usage#testing-and-dependencies) that have runtime dependencies. Run tests before pushing your code to CI, and avoid having to mock or stub your own services.
-- Define [tasks](https://github.com/garden-io/garden/tree/master/examples/tasks) that run as part of your deployment process, e.g. database migrations or scaffolding.
+- Define [tasks](https://github.com/garden-io/garden/tree/master/examples/tasks) that run as part of your deployment process—e.g. database migrations or scaffolding.
 - [Hot reload](https://docs.garden.io/using-garden/hot-reload) lets you near-instantaneously update code and static files in containers as they run, for services that support in-place reloading.
 - [Remote sources](https://docs.garden.io/examples/remote-sources) support allows your project to automatically pull code from different repositories.
 - The built-in web **dashboard** gives you a full overview of your stack (and many more UI features are planned to further aid with development).
@@ -33,27 +33,27 @@ _Note: The project is in beta. APIs may still change slightly across  versions,
 
 Head over to the [Basics](https://docs.garden.io/basics) section in our documentation for details
 on how to set up and use Garden, or look through our [Simple Project](https://docs.garden.io/examples/simple-project)
-guide to get a quick sense of how it works.
+guide for a brief introduction to how it works.
 
 ## Documentation
 
-You can find the full Garden documentation at [https://docs.garden.io](https://docs.garden.io/).
+You can find Garden's full documentation at [https://docs.garden.io](https://docs.garden.io/).
 
 Overview:
 
-- [Basics](https://docs.garden.io/basics), for installation instructions, our quick start guide, and an overview of the main concepts around Garden.
-- [Using Garden](https://docs.garden.io/using-garden), for features and usage, Garden configuration files, usage with remote clusters, and setting up hot reload.
-- [Example Projects](https://docs.garden.io/examples) contains guides based on some of the [examples](https://github.com/garden-io/garden/tree/v0.9.6/examples).
-- [Reference](https://docs.garden.io/reference), for the glossary, commands reference, configuration files reference, and template strings reference.
+- [Basics](https://docs.garden.io/basics)—installation instructions, our quick start guide, and an overview of the main concepts around Garden.
+- [Using Garden](https://docs.garden.io/using-garden)—features and usage, Garden configuration files, usage with remote clusters, and setting up hot reload.
+- [Example Projects](https://docs.garden.io/examples)—guides based on some of the [examples](https://github.com/garden-io/garden/tree/v0.9.6/examples).
+- [Reference](https://docs.garden.io/reference)—glossary, commands reference, configuration files reference, and template strings reference.
 - [FAQs](https://docs.garden.io/faqs).
 
 ## Examples
 
-There are examples of how to use Garden in a myriad of different ways in the [examples](https://github.com/garden-io/garden/tree/v0.9.3/examples) folder of our repository.
+The [examples](https://github.com/garden-io/garden/tree/v0.9.3/examples) folder of our repository shows a myriad of different ways to use Garden.
 
 For written guides based on some of these examples, check out the [examples section](https://docs.garden.io/examples) of our documentation.
 
-Here are some simple examples of how Garden configuration files look:
+Here are a few simple examples of Garden configuration files:
 
 ```yaml
 kind: Module
@@ -95,11 +95,11 @@ Please browse our [examples directory](https://github.com/garden-io/garden/tree/
 
 ## Support
 
-Please join the Garden [Slack workspace](http://chat.garden.io) to ask questions, discuss how Garden might fit into your workflow, or even just chat about all things DevOps.
+Please join the Garden [Slack workspace](http://chat.garden.io) to ask questions, discuss how Garden might fit into your workflow, or just chat about all things DevOps.
 
 ## Acknowledgements
 
-Garden would not be possible without an amazing ecosystem of open-source projects. Here are just some of the projects that Garden uses, either directly or indirectly:
+Garden would not be possible without an amazing ecosystem of open-source projects. Here are some of the projects that Garden uses, either directly or indirectly:
 
 - [Kubernetes](https://kubernetes.io/)
 - [OpenFaaS](https://www.openfaas.com/)

docs/basics/README.md

@@ -8,4 +8,4 @@ The following articles cover the basics of installing and using Garden:
 
 If you're already familiar with the basics, feel free to move on to the next chapter: [Using Garden](../using-garden/README.md).
 
-Or dive right in by exploring our [configuration files](../using-garden/configuration-files.md) and [Example projects](../examples/README.md).
+Or dive right in by exploring our [configuration files](../using-garden/configuration-files.md) and [Example Projects](../examples/README.md).

docs/basics/installation.md

@@ -18,7 +18,7 @@ steps below if you prefer.
 
 #### Step 1: Install Homebrew
 
-If you haven't already set up homebrew, please follow [their instructions](https://brew.sh/) to set it up.
+If you haven't already set up Homebrew, please follow [their installation instructions](https://brew.sh/).
 
 #### Step 2: Docker and local Kubernetes
 
@@ -37,7 +37,7 @@ configure and use, but we do fully support it on Mac. Please look at the
 
 #### Step 3: Install `garden-cli`
 
-We have a Homebrew tap and package that you can use to easily install `garden-cli` and all dependencies:
+We have a Homebrew tap and package that you can use to easily install `garden-cli` and its dependencies:
 
 ```sh
 brew tap garden-io/garden
@@ -50,10 +50,7 @@ To later upgrade to the newest version, simply run `brew update` and then `brew
 
 You can run Garden on Windows 10 Pro or Enterprise editions (the Home edition unfortunately does not work because it does not include support for virtualization).
 
-To install the Garden CLI, please use our automated installation script, which will
-check for dependencies, install missing dependencies if needed, and finally install the Garden CLI.
-
-To run the script, open PowerShell as an Administrator and run:
+To install the Garden CLI and its dependencies, please use our installation script. To run the script, open PowerShell as an administrator and run:
 
 ```PowerShell
 Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/garden-io/garden/master/support/install.ps1'))
@@ -64,7 +61,7 @@ The things the script will check for are the following:
 * The [Chocolatey](https://chocolatey.org) package manager. The script installs it automatically if necessary.
 * _git_, _rsync_ and _Docker for Windows_. The script will install or upgrade those via Chocolatey.
 * Whether you have Hyper-V enabled. This is required for _Docker for Windows_. If you do not already have it enabled,
-  the script will enable it but you will need to restart your computer before starting Docker for Windows.
+  the script will enable it, but you will need to restart your computer before starting Docker for Windows.
 * Whether you have Kubernetes enabled in your _Docker for Windows_ installation.
 
 To later upgrade to the newest version, simply re-run the above script.
@@ -129,12 +126,12 @@ since it uses the `local-kubernetes` plugin by default, but you can configure it
 `garden.yml` as follows:
 
 ```yaml
-project:
-  environments:
-    - name: local
-      providers:
-        - name: local-kubernetes
-          context: minikube
+kind: Project
+environments:
+  - name: local
+    providers:
+      - name: local-kubernetes
+        context: minikube
 ```
 
 If you happen to have installed both Minikube and a version of Docker for Mac with Kubernetes support enabled,

docs/basics/quick-start.md

@@ -4,9 +4,9 @@ This guide will walk you through setting up the Garden framework. It assumes you
 
 ## Using the CLI
 
-With the CLI installed, we can now try out a few commands using the [Simple Project](../examples/simple-project.md) from our [example projects](../examples/README.md). The example project consists of a couple of simple modules, each defining one service.
+With the CLI installed, we can now try out a few commands using the [Simple Project](../examples/simple-project.md) from our [example projects](../examples/README.md). The example project consists of a couple of basic modules, each defining one service.
 
-_Note: Check if Kubernetes is running with `kubectl version`. You should see both a `Client Version` and a `Server Version` in the response. If not, please start it up before proceeding._
+_Note: Check whether Kubernetes is running with `kubectl version`. You should see both a `Client Version` and a `Server Version` in the response. If not, please start it up before proceeding._
 
 Clone the repo and change into the `simple-project`  directory:
 
@@ -33,7 +33,7 @@ This builds Docker images for `go-service` and `node-service` respectively. Next
 garden deploy
 ```
 
-And that's it! The `garden build` step above is actually unnecessary (only included here for clarity), since `garden deploy` will also rebuild modules as needed. The services are now running on the Garden framework. You can see for yourself by querying the `/hello` endpoint of `go-service`'s running container:
+And that's it! The `garden build` step above is actually unnecessary (only included here for clarity), since `garden deploy` will also rebuild modules as needed. The services are now running in your Kubernetes cluster. You can see for yourself by querying the `/hello` endpoint of `go-service`'s running container:
 
 ```sh
 garden call go-service/hello-go

docs/basics/stack-graph.md

@@ -2,20 +2,20 @@
 
 Garden centers around the _Stack Graph_, which allows you to describe your whole stack in a consistent, structured way.
 
-Garden uses the graph to detect when modules need to re-built or re-tested, services re-deployed etc., by looking at your current code and comparing against previously built, deployed and tested versions.
+Garden uses the graph to detect when modules need to be re-built or re-tested, services re-deployed etc. by comparing your current code with previously built, deployed and tested versions.
 
 ## Structure
 
 The Stack Graph is essentially an opinionated graph structure, with a handful of pre-defined entity types and verbs:
 
 * **Project**: The root of the graph. Contains one or more _modules_ and configures _providers_.
 * **Provider**: Providers are configured at the project level. They take care of initializing deployment environments, and control what happens within each node of the graph, e.g. how modules are built, services are deployed etc. They also specify _module types_ and how they are configured.
-* **Module**: A module is something you _build_. Each module specifies a type (e.g. `container` or `helm`) which dictates how it is configured, deployed etc. It can contain zero or more _services_, _tasks_ and _tests_. It can also have build dependencies.
+* **Module**: A module is something you _build_. Each module specifies a type (e.g. `container` or `helm`) which dictates how it is configured, built, deployed etc. It can contain zero or more _services_, _tasks_ and _tests_. It can also have build dependencies.
 * **Service**: A service is something you _deploy_. It can depend on other services, as well as tasks.
 * **Task**: A task is something you _run_ and wait for to finish. It can depend on other services and tasks.
 * **Test**: A test is also something you run and wait for to finish, similar to tasks, but with slightly different semantics and separate commands for execution. It can depend on services and tasks (but notably services and tasks cannot depend on tests).
 
-Each part of your stack _describes itself_ using a simple configuration file, and Garden collects all those declarations, validates, and compiles them into a DAG (a directed acyclic graph, meaning it should have no circular dependencies).
+Each part of your stack _describes itself_ using a simple configuration file. Garden collects all those declarations, validates, and compiles them into a DAG (a directed acyclic graph, meaning it should have no circular dependencies).
 
 Importantly, what happens within each of the actions that the graph describes—building, deploying, running etc.—is completely pluggable via the providers. The Stack Graph is only opinionated in terms of flows and dependencies—_what_ should happen _when_—but the _how_ is pluggable.
 
@@ -53,7 +53,7 @@ tests:
   dependencies: [my-other-service]
 ```
 
-Note here the first four fields, which are common across all module types. Other fields are specified by the corresponding _provider_.
+Note here the first four fields, which are common across all module types—`kind`, `type`, `name` and `description`. Other fields are specified by the corresponding _provider_.
 
 Also notice that the `container` module explicitly declares a service, whereas the `helm` module does not. This is dictated by the provider. Containers often only need to be built (e.g. base images for other containers), or may contain multiple services. A Helm chart , however, is generally a single deployable so the provider makes the service implicit when configuring it.
 

docs/reference/glossary.md

@@ -8,30 +8,30 @@ Several named environment configurations may be defined (e.g. _dev_, _testing_,
 `garden.yml`](../using-garden/configuration-files.md#project-configuration).
 
 #### Module
-The basic unit of configuration in Garden. A module is defined by its
-[`garden.yml` configuration file](./config.md), located in the module's top-level
-directory,
-which
-is a subdirectory of the [project](#project) repository's top-level directory.
+The unit of building in Garden. A module is defined by its [`garden.yml` configuration file](./config.md),
+located in the module's top-level directory.
 
 Each module has a plugin type, and may define one or more [services](#service).
 
 Essentially, a project is organized into modules at the granularity of its *build* steps. A module's build step may
 depend on one or more other modules having already been built, as specified in its `garden.yml`, in which case those modules will be built
 first, and their build output made available to the requiring module's build step.
 
-#### Provider
-A [module's](#module) plugin type defines its behavior when it is built, deployed, run and tested. Currently, `container` (for "standard" containerized services) and `openfaas` (for serverless functions) are the only stable plugin types.
-
 #### Project
 The top-level unit of organization in Garden. A project consists of one or more [modules](#module), along with a
 project-level [`garden.yml` configuration file](./config.md).
 
-Garden CLI commands are run in the context of a project, and are aware of all its modules and services.
+Garden CLI commands are run in the context of a project, and are aware of all its configuration, modules and services.
 
 #### Provider
 An implementation of a plugin type (e.g. `local-kubernetes` for the `container` plugin).
 
+Whenever "a module's type" is mentioned in the documentation, what's meant is "which provider will handle this module?" Providers are responsible for implementing a module type's behaviors—e.g. how to build, deploy or test the module. Providers need to be specified for all the module types used in the project.
+
+For example, both the `local-kubernetes` and `kubernetes` providers (`kubernetes` is the provider for remote Kubernetes) implement the `container` module type, but they handle deployments differently. `local-kubernetes` deploys to a local cluster, where `kubernetes` deploys to a remote cluster.
+
+For a comprehensive list of providers available in Garden, check out the [References](../reference/README.md)
+
 #### Service
 The unit of deployment in Garden. Services are defined in their parent [module](#module)'s `garden.yml`, each
 exposing [one or more ingress endpoints](./config.md#container).

docs/using-garden/README.md

@@ -2,20 +2,20 @@
 
 ## [Features and usage](./features-and-usage.md)
 
-In this article we discuss how to start a new project with `garden create`, the basic development workflow, how Garden's providers work, and the basics of testing and dependencies.
+In this article we discuss how to set up a new Garden project, the basic development workflow, how Garden's providers work, and the basics of testing and dependencies.
 
 ## [Configuration files](./configuration-files.md)
 
-This one is all about Garden's configuration files. The difference between project and module configs, some significant specific fields, setting up services, and a primer on tests.
+This one is all about Garden's configuration files—an overview of project and module configs, setting up services, and a primer on tests.
 
 ## [Remote Clusters](./remote-clusters.md)
 
-Most of the time we want to develop locally, with our project running in Minikube or Docker. If you'd like to use a remote cluster though, check out this guide.
+Most of these guides currently focus on local development. If you'd like to use a remote cluster, though, check out this guide.
 
 ## [Hot Reload](./hot-reload.md)
 
-This article discusses how to use hot reloading, so that you can update running services on the fly as you make changes to their code, without losing state and without having to destroy and re-create your container.
+This article discusses how to use hot reloading, so that you can update running services on the fly as you make changes to their code, without losing state and without having to destroy and re-create containers.
 
 ## [Using Helm charts](./using-helm-charts.md)
 
-The [Helm](https://helm.sh/) package manager is one of the most commonly used tools for managing Kubernetes manifests. Garden supports using your own Helm charts, alongside your container modules. This guide shows you how to use 3rd-party (or otherwise external) Helm charts, as well as your own charts in your Garden project. We also go through how to configure tests, tasks and hot-reloading for your charts.
+The [Helm](https://helm.sh/) package manager is one of the most commonly used tools for managing Kubernetes manifests. Garden supports using your own Helm charts, alongside your container modules. This guide shows you how to use 3rd-party (or otherwise external) Helm charts, as well as your own charts, in your Garden project. We also go through how to configure tests, tasks and hot-reloading for your charts.