From d562fe284223716666fc438269575801f528c4f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ey=C3=BE=C3=B3r=20Magn=C3=BAsson?= <eysi09@gmail.com>
Date: Wed, 31 Oct 2018 12:07:41 +0100
Subject: [PATCH 1/4] refactor(cli): remove single char command aliases

---
 garden-service/src/commands/create/create.ts  | 1 -
 garden-service/src/commands/create/module.ts  | 1 -
 garden-service/src/commands/create/project.ts | 1 -
 garden-service/src/commands/exec.ts           | 1 -
 garden-service/src/commands/run/module.ts     | 1 -
 garden-service/src/commands/run/run.ts        | 1 -
 garden-service/src/commands/run/service.ts    | 1 -
 garden-service/src/commands/run/test.ts       | 1 -
 8 files changed, 8 deletions(-)

diff --git a/garden-service/src/commands/create/create.ts b/garden-service/src/commands/create/create.ts
index f79de0465a..e64195af59 100644
--- a/garden-service/src/commands/create/create.ts
+++ b/garden-service/src/commands/create/create.ts
@@ -12,7 +12,6 @@ import { CreateModuleCommand } from "./module"
 
 export class CreateCommand extends Command {
   name = "create"
-  alias = "r"
   help = "Create a new project or add a new module"
 
   subCommands = [
diff --git a/garden-service/src/commands/create/module.ts b/garden-service/src/commands/create/module.ts
index 8e3246b7ae..8183ffedfc 100644
--- a/garden-service/src/commands/create/module.ts
+++ b/garden-service/src/commands/create/module.ts
@@ -53,7 +53,6 @@ interface CreateModuleResult extends CommandResult {
 
 export class CreateModuleCommand extends Command<Args, Opts> {
   name = "module"
-  alias = "m"
   help = "Creates a new Garden module."
 
   description = dedent`
diff --git a/garden-service/src/commands/create/project.ts b/garden-service/src/commands/create/project.ts
index 8a51471452..5d86a1459a 100644
--- a/garden-service/src/commands/create/project.ts
+++ b/garden-service/src/commands/create/project.ts
@@ -64,7 +64,6 @@ interface CreateProjectResult extends CommandResult {
 
 export class CreateProjectCommand extends Command<Args, Opts> {
   name = "project"
-  alias = "p"
   help = "Creates a new Garden project."
 
   description = dedent`
diff --git a/garden-service/src/commands/exec.ts b/garden-service/src/commands/exec.ts
index 801be5e119..833940371b 100644
--- a/garden-service/src/commands/exec.ts
+++ b/garden-service/src/commands/exec.ts
@@ -40,7 +40,6 @@ type Args = typeof runArgs
 
 export class ExecCommand extends Command<Args> {
   name = "exec"
-  alias = "e"
   help = "Executes a command (such as an interactive shell) in a running service."
 
   description = dedent`
diff --git a/garden-service/src/commands/run/module.ts b/garden-service/src/commands/run/module.ts
index ddb761d501..0551ad4b9c 100644
--- a/garden-service/src/commands/run/module.ts
+++ b/garden-service/src/commands/run/module.ts
@@ -51,7 +51,6 @@ type Opts = typeof runOpts
 
 export class RunModuleCommand extends Command<Args, Opts> {
   name = "module"
-  alias = "m"
   help = "Run an ad-hoc instance of a module."
 
   description = dedent`
diff --git a/garden-service/src/commands/run/run.ts b/garden-service/src/commands/run/run.ts
index 506b474c7d..455b89a85c 100644
--- a/garden-service/src/commands/run/run.ts
+++ b/garden-service/src/commands/run/run.ts
@@ -17,7 +17,6 @@ import { Garden } from "../../garden"
 
 export class RunCommand extends Command {
   name = "run"
-  alias = "r"
   help = "Run ad-hoc instances of your modules, services and tests"
 
   subCommands = [
diff --git a/garden-service/src/commands/run/service.ts b/garden-service/src/commands/run/service.ts
index 8612752a14..f2b097be7d 100644
--- a/garden-service/src/commands/run/service.ts
+++ b/garden-service/src/commands/run/service.ts
@@ -36,7 +36,6 @@ type Opts = typeof runOpts
 
 export class RunServiceCommand extends Command<Args, Opts> {
   name = "service"
-  alias = "s"
   help = "Run an ad-hoc instance of the specified service"
 
   description = dedent`
diff --git a/garden-service/src/commands/run/test.ts b/garden-service/src/commands/run/test.ts
index c2506c7703..31a31fea96 100644
--- a/garden-service/src/commands/run/test.ts
+++ b/garden-service/src/commands/run/test.ts
@@ -49,7 +49,6 @@ type Opts = typeof runOpts
 
 export class RunTestCommand extends Command<Args, Opts> {
   name = "test"
-  alias = "t"
   help = "Run the specified module test."
 
   description = dedent`

From cc47d644903534181ef7e604b58cb5dcab32dd7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ey=C3=BE=C3=B3r=20Magn=C3=BAsson?= <eysi09@gmail.com>
Date: Wed, 31 Oct 2018 12:19:19 +0100
Subject: [PATCH 2/4] refactor(docs): re-name auto generated reference files

---
 garden-service/src/docs/commands.ts | 2 +-
 garden-service/src/docs/config.ts   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/garden-service/src/docs/commands.ts b/garden-service/src/docs/commands.ts
index ee74ea22c6..74eb0f3929 100644
--- a/garden-service/src/docs/commands.ts
+++ b/garden-service/src/docs/commands.ts
@@ -19,7 +19,7 @@ import { describeParameters } from "../commands/base"
 
 export function generateCommandReferenceDocs(docsRoot: string) {
   const referenceDir = resolve(docsRoot, "reference")
-  const outputPath = resolve(referenceDir, "commands.md")
+  const outputPath = resolve(referenceDir, "command-reference.md")
 
   const commands = flatten(coreCommands.map(cmd => {
     if (cmd.subCommands && cmd.subCommands.length) {
diff --git a/garden-service/src/docs/config.ts b/garden-service/src/docs/config.ts
index 4e3ba79439..8ba204dee3 100644
--- a/garden-service/src/docs/config.ts
+++ b/garden-service/src/docs/config.ts
@@ -169,7 +169,7 @@ export function renderSchemaDescription(description: Joi.Description, opts: Rend
 
 export function generateConfigReferenceDocs(docsRoot: string) {
   const referenceDir = resolve(docsRoot, "reference")
-  const outputPath = resolve(referenceDir, "config.md")
+  const outputPath = resolve(referenceDir, "config-files-reference.md")
 
   const yaml = renderSchemaDescription(configSchema.describe(), { required: true })
   const moduleTypes = builtInModuleTypes.map(({ name, schema }) => {

From d04e97bb7d3831ef2c83b98e4130d2ddf32697eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ey=C3=BE=C3=B3r=20Magn=C3=BAsson?= <eysi09@gmail.com>
Date: Wed, 31 Oct 2018 12:20:19 +0100
Subject: [PATCH 3/4] refactor(docs): improve cli commands help and description
 text

---
 docs/reference/command-reference.md           | 137 +++++++++---------
 garden-service/src/cli/cli.ts                 |   2 +-
 garden-service/src/commands/base.ts           |   2 +-
 garden-service/src/commands/build.ts          |   2 +-
 garden-service/src/commands/call.ts           |   4 +-
 garden-service/src/commands/create/module.ts  |   6 +-
 garden-service/src/commands/create/project.ts |  12 +-
 garden-service/src/commands/delete.ts         |   2 +-
 garden-service/src/commands/deploy.ts         |   8 +-
 garden-service/src/commands/dev.ts            |   5 +-
 garden-service/src/commands/link/module.ts    |   2 +-
 garden-service/src/commands/link/source.ts    |   2 +-
 garden-service/src/commands/logs.ts           |   4 +-
 garden-service/src/commands/publish.ts        |   4 +-
 garden-service/src/commands/run/service.ts    |   6 +-
 garden-service/src/commands/test.ts           |  20 +--
 garden-service/src/commands/unlink/module.ts  |   6 +-
 garden-service/src/commands/unlink/source.ts  |   6 +-
 .../src/commands/update-remote/modules.ts     |   6 +-
 .../src/commands/update-remote/sources.ts     |   6 +-
 .../src/docs/templates/commands.hbs           |   2 +-
 21 files changed, 120 insertions(+), 124 deletions(-)

diff --git a/docs/reference/command-reference.md b/docs/reference/command-reference.md
index a5ba48435e..069f5c74eb 100644
--- a/docs/reference/command-reference.md
+++ b/docs/reference/command-reference.md
@@ -2,7 +2,7 @@
 
 Below is a list of Garden CLI commands and usage information.
 
-The commands should be run in a Garden project root, and are always scoped to that project.
+The commands should be run in a Garden project, and are always scoped to that project.
 
 Note: You can get a list of commands in the CLI by running `garden -h/--help`,
 and detailed help for each command using `garden <command> -h/--help`
@@ -15,8 +15,8 @@ The following option flags can be used with any of the CLI commands:
 | -------- | ----- | ---- | ----------- |
   | `--root` | `-r` | string | Override project root directory (defaults to working directory).
   | `--silent` | `-s` | boolean | Suppress log output.
-  | `--env` | `-e` | string | The environment (and optionally namespace) to work against
-  | `--loglevel` | `-l` | `error` `warn` `info` `verbose` `debug` `silly` `0` `1` `2` `3` `4` `5`  | Set logger level. Values can be either string or numeric and are prioritized from 0 to 5 (highest to lowest) as follows: error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5
+  | `--env` | `-e` | string | The environment (and optionally namespace) to work against.
+  | `--loglevel` | `-l` | `error` `warn` `info` `verbose` `debug` `silly` `0` `1` `2` `3` `4` `5`  | Set logger level. Values can be either string or numeric and are prioritized from 0 to 5 (highest to lowest) as follows: error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5.
   | `--output` | `-o` | `json` `yaml`  | Output command result in specified format (note: disables progress logging).
   | `--emoji` |  | boolean | Enable emoji in output (defaults to true if the environment supports it).
 
@@ -42,7 +42,7 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `module` | No | Specify module(s) to build. Use comma separator to specify multiple modules.
+  | `module` | No | Specify module(s) to build. Use comma as a separator to specify multiple modules.
 
 ##### Options
 
@@ -73,13 +73,13 @@ Note: Currently only supports simple GET requests for HTTP/HTTPS ingresses.
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `serviceAndPath` | Yes | The name of the service(s) to call followed by the ingress path (e.g. my-container/somepath).
+  | `serviceAndPath` | Yes | The name(s) of the service(s) to call followed by the ingress path (e.g. my-container/somepath).
 
 ### garden create project
 
 Creates a new Garden project.
 
-The 'create project' command walks the user through setting up a new Garden project and
+This command walks the user through setting up a new Garden project and
 generates scaffolding based on user input.
 
 Examples:
@@ -87,8 +87,8 @@ Examples:
     garden create project # creates a new Garden project in the current directory (project name defaults to
     directory name)
     garden create project my-project # creates a new Garden project in my-project directory
-    garden create project --module-dirs=path/to/modules1,path/to/modules2
-    # creates a new Garden project and looks for pre-existing modules in the modules1 and modules2 directories
+    garden create project --module-dirs=path/to/modules-a,path/to/modules-b
+    # creates a new Garden project and looks for pre-existing modules in the modules-a and modules-b directories
     garden create project --name my-project
     # creates a new Garden project in the current directory and names it my-project
 
@@ -100,21 +100,19 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `project-dir` | No | Directory of the project. (Defaults to current directory.)
+  | `project-dir` | No | Directory of the project (defaults to current directory).
 
 ##### Options
 
 | Argument | Alias | Type | Description |
 | -------- | ----- | ---- | ----------- |
-  | `--module-dirs` |  | array:path | Relative path to modules directory. Use comma as a separator to specify multiple directories
-  | `--name` |  | string | Assigns a custom name to the project. (Defaults to name of the current directory.)
+  | `--module-dirs` |  | array:path | Relative path to modules directory. Use comma as a separator to specify multiple directories.
+  | `--name` |  | string | Assigns a custom name to the project (defaults to name of the current directory).
 
 ### garden create module
 
 Creates a new Garden module.
 
-Creates a new Garden module of the given type
-
 Examples:
 
     garden create module # creates a new module in the current directory (module name defaults to directory name)
@@ -130,13 +128,13 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `module-dir` | No | Directory of the module. (Defaults to current directory.)
+  | `module-dir` | No | Directory of the module (defaults to current directory).
 
 ##### Options
 
 | Argument | Alias | Type | Description |
 | -------- | ----- | ---- | ----------- |
-  | `--name` |  | string | Assigns a custom name to the module. (Defaults to name of the current directory.)
+  | `--name` |  | string | Assigns a custom name to the module (defaults to name of the current directory)
   | `--type` |  | `container` `google-cloud-function` `npm-package`  | Type of module.
 
 ### garden delete secret
@@ -195,28 +193,26 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `service` | Yes | The name of the service(s) to delete. Use comma as separator to specify multiple services.
+  | `service` | Yes | The name(s) of the service(s) to delete. Use comma as a separator to specify multiple services.
 
 ### garden deploy
 
 Deploy service(s) to your environment.
 
+Deploys all or specified services, taking into account service dependency order.
+Also builds modules and dependencies if needed.
 
-    Deploys all or specified services, taking into account service dependency order.
-    Also builds modules and dependencies if needed.
-
-    Optionally stays running and automatically re-builds and re-deploys services if their module source
-    (or their dependencies' sources) change.
+Optionally stays running and automatically re-builds and re-deploys services if their module source
+(or their dependencies' sources) change.
 
-    Examples:
+Examples:
 
-        garden deploy                         # deploy all modules in the project
-        garden deploy my-service              # only deploy my-service
-        garden deploy --force                 # force re-deploy of modules, even if they're already deployed
-        garden deploy --watch                 # watch for changes to code
-        garden deploy --hot-reload=my-service # deploys all services, with hot reloading enabled for my-service
-        garden deploy --env stage             # deploy your services to an environment called stage
-  
+    garden deploy                         # deploy all modules in the project
+    garden deploy my-service              # only deploy my-service
+    garden deploy --force                 # force re-deploy of modules, even if they're already deployed
+    garden deploy --watch                 # watch for changes to code
+    garden deploy --hot-reload=my-service # deploys all services, with hot reloading enabled for my-service
+    garden deploy --env stage             # deploy your services to an environment called stage
 
 ##### Usage
 
@@ -226,7 +222,7 @@ Deploy service(s) to your environment.
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `service` | No | The name(s) of the service(s) to deploy (skip to deploy all services). Use comma as separator to specify multiple services.
+  | `service` | No | The name(s) of the service(s) to deploy (skip to deploy all services). Use comma as a separator to specify multiple services.
 
 ##### Options
 
@@ -235,22 +231,20 @@ Deploy service(s) to your environment.
   | `--force` |  | boolean | Force redeploy of service(s).
   | `--force-build` |  | boolean | Force rebuild of module(s).
   | `--watch` | `-w` | boolean | Watch for changes in module(s) and auto-deploy.
-  | `--hot-reload` |  | array:string | The name(s) of the service(s) to deploy with hot reloading enabled. Use comma as separator to specify multiple services. When this option is used, the command is run in watch mode (i.e. implicitly assumes the --watch/-w flag).
+  | `--hot-reload` |  | array:string | The name(s) of the service(s) to deploy with hot reloading enabled. Use comma as a separator to specify multiple services. When this option is used, the command is run in watch mode (i.e. implicitly assumes the --watch/-w flag).
 
 ### garden dev
 
 Starts the garden development console.
 
+The Garden dev console is a combination of the `build`, `deploy` and `test` commands.
+It builds, deploys and tests all your modules and services, and re-builds, re-deploys and re-tests
+as you modify the code.
 
-    The Garden dev console is a combination of the `build`, `deploy` and `test` commands.
-    It builds, deploys and tests all your modules and services, and re-builds, re-deploys and re-tests
-    as you modify the code.
-
-    Examples:
+Examples:
 
-        garden dev
-        garden dev --hot-reload=foo-service,bar-service # enable hot reloading for foo-service and bar-service
-  
+    garden dev
+    garden dev --hot-reload=foo-service,bar-service # enable hot reloading for foo-service and bar-service
 
 ##### Usage
 
@@ -260,7 +254,7 @@ Starts the garden development console.
 
 | Argument | Alias | Type | Description |
 | -------- | ----- | ---- | ----------- |
-  | `--hot-reload` |  | array:string | The name(s) of the service(s) to deploy with hot reloading enabled. Use comma as separator to specify multiple services.
+  | `--hot-reload` |  | array:string | The name(s) of the service(s) to deploy with hot reloading enabled. Use comma as a separator to specify multiple services.
 
 ### garden exec
 
@@ -345,7 +339,7 @@ Link a remote source to a local directory.
 
 After linking a remote source, Garden will read it from its local directory instead of
 from the remote URL. Garden can only link remote sources that have been declared in the project
-level garden.yml config.
+level `garden.yml` config.
 
 Examples:
 
@@ -368,7 +362,7 @@ Link a module to a local directory.
 
 After linking a remote module, Garden will read the source from the module's local directory instead of from
 the remote URL. Garden can only link modules that have a remote source,
-i.e. modules that specifiy a repositoryUrl in their garden.yml config file.
+i.e. modules that specifiy a `repositoryUrl` in their `garden.yml` config file.
 
 Examples:
 
@@ -405,7 +399,7 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `service` | No | The name of the service(s) to logs (skip to logs all services). Use comma as separator to specify multiple services.
+  | `service` | No | The name(s) of the service(s) to log (skip to log all services). Use comma as a separator to specify multiple services.
 
 ##### Options
 
@@ -435,7 +429,7 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `module` | No | The name of the module(s) to publish (skip to publish all modules). Use comma as separator to specify multiple modules.
+  | `module` | No | The name(s) of the module(s) to publish (skip to publish all modules). Use comma as a separator to specify multiple modules.
 
 ##### Options
 
@@ -476,7 +470,7 @@ Examples:
 
 ### garden run service
 
-Run an ad-hoc instance of the specified service
+Run an ad-hoc instance of the specified service.
 
 This can be useful for debugging or ad-hoc experimentation with services.
 
@@ -492,13 +486,13 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `service` | Yes | The service to run
+  | `service` | Yes | The service to run.
 
 ##### Options
 
 | Argument | Alias | Type | Description |
 | -------- | ----- | ---- | ----------- |
-  | `--force-build` |  | boolean | Force rebuild of module
+  | `--force-build` |  | boolean | Force rebuild of module.
 
 ### garden run test
 
@@ -569,21 +563,19 @@ Examples:
 
 Test all or specified modules.
 
+Runs all or specified tests defined in the project. Also builds modules and dependencies,
+and deploys service dependencies if needed.
 
-    Runs all or specified tests defined in the project. Also builds modules and dependencies,
-    and deploy service dependencies if needed.
-
-    Optionally stays running and automatically re-runs tests if their module source
-    (or their dependencies' sources) change.
+Optionally stays running and automatically re-runs tests if their module source
+(or their dependencies' sources) change.
 
-    Examples:
+Examples:
 
-        garden test              # run all tests in the project
-        garden test my-module    # run all tests in the my-module module
-        garden test -n integ     # run all tests with the name 'integ' in the project
-        garden test --force      # force tests to be re-run, even if they're already run successfully
-        garden test --watch      # watch for changes to code
-  
+    garden test               # run all tests in the project
+    garden test my-module     # run all tests in the my-module module
+    garden test --name integ  # run all tests with the name 'integ' in the project
+    garden test --force       # force tests to be re-run, even if they've already run successfully
+    garden test --watch       # watch for changes to code
 
 ##### Usage
 
@@ -593,7 +585,7 @@ Test all or specified modules.
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `module` | No | The name of the module(s) to deploy (skip to test all modules). Use comma as separator to specify multiple modules.
+  | `module` | No | The name(s) of the module(s) to test (skip to test all modules). Use comma as a separator to specify multiple modules.
 
 ##### Options
 
@@ -613,8 +605,8 @@ of its local directory.
 
 Examples:
 
-    garden unlink source my-source # unlinks my-source
-    garden unlink source --all # unlinks all sources
+    garden unlink source my-source  # unlinks my-source
+    garden unlink source --all      # unlinks all sources
 
 ##### Usage
 
@@ -624,7 +616,7 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `source` | No | Name of the source(s) to unlink. Use comma separator to specify multiple sources.
+  | `source` | No | The name(s) of the source(s) to unlink. Use comma as a separator to specify multiple sources.
 
 ##### Options
 
@@ -641,8 +633,8 @@ its remote URL instead of its local directory.
 
 Examples:
 
-    garden unlink module my-module # unlinks my-module
-    garden unlink module --all # unlink all modules
+    garden unlink module my-module  # unlinks my-module
+    garden unlink module --all      # unlink all modules
 
 ##### Usage
 
@@ -652,7 +644,7 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `module` | No | Name of the module(s) to unlink. Use comma separator to specify multiple modules.
+  | `module` | No | The name(s) of the module(s) to unlink. Use comma as a separator to specify multiple modules.
 
 ##### Options
 
@@ -664,11 +656,11 @@ Examples:
 
 Update remote sources.
 
-Update the remote sources declared in the project config.
+This command updates the remote sources declared in the project level `garden.yml` config file.
 
 Examples:
 
-    garden update-remote sources            # update all remote sources in the project config
+    garden update-remote sources            # update all remote sources
     garden update-remote sources my-source  # update remote source my-source
 
 ##### Usage
@@ -679,14 +671,14 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `source` | No | Name of the remote source(s) to update. Use comma separator to specify multiple sources.
+  | `source` | No | The name(s) of the remote source(s) to update. Use comma as a separator to specify multiple sources.
 
 ### garden update-remote modules
 
 Update remote modules.
 
-Remote modules are modules that have a repositoryUrl field
-in their garden.yml config that points to a remote repository.
+This command updates remote modules, i.e. modules that have a `repositoryUrl` field
+in their `garden.yml` config that points to a remote repository.
 
 Examples:
 
@@ -701,7 +693,7 @@ Examples:
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-  | `module` | No | Name of the remote module(s) to update. Use comma separator to specify multiple modules.
+  | `module` | No | The name(s) of the remote module(s) to update. Use comma as a separator to specify multiple modules.
 
 ### garden update-remote all
 
@@ -724,3 +716,4 @@ Throws an error and exits with code 1 if something's not right in your garden.ym
 ##### Usage
 
     garden validate 
+
diff --git a/garden-service/src/cli/cli.ts b/garden-service/src/cli/cli.ts
index 8bd527a218..65f153899d 100644
--- a/garden-service/src/cli/cli.ts
+++ b/garden-service/src/cli/cli.ts
@@ -116,7 +116,7 @@ export const GLOBAL_OPTIONS = {
     choices: logLevelChoices,
     help:
       "Set logger level. Values can be either string or numeric and are prioritized from 0 to 5 " +
-      "(highest to lowest) as follows: error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5",
+      "(highest to lowest) as follows: error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5.",
     hints:
       "[enum] [default: info] [error || 0, warn || 1, info || 2, verbose || 3, debug || 4, silly || 5]",
     defaultValue: LogLevel[LogLevel.info],
diff --git a/garden-service/src/commands/base.ts b/garden-service/src/commands/base.ts
index e10bebb9ad..19b2b9553d 100644
--- a/garden-service/src/commands/base.ts
+++ b/garden-service/src/commands/base.ts
@@ -162,7 +162,7 @@ export class BooleanParameter extends Parameter<boolean> {
 
 // TODO: maybe this should be a global option?
 export class EnvironmentOption extends StringParameter {
-  constructor({ help = "The environment (and optionally namespace) to work against" } = {}) {
+  constructor({ help = "The environment (and optionally namespace) to work against." } = {}) {
     super({
       help,
       required: false,
diff --git a/garden-service/src/commands/build.ts b/garden-service/src/commands/build.ts
index 2fa53e9789..be2289ee35 100644
--- a/garden-service/src/commands/build.ts
+++ b/garden-service/src/commands/build.ts
@@ -24,7 +24,7 @@ import { hotReloadAndLog } from "./helpers"
 
 const buildArguments = {
   module: new StringsParameter({
-    help: "Specify module(s) to build. Use comma separator to specify multiple modules.",
+    help: "Specify module(s) to build. Use comma as a separator to specify multiple modules.",
   }),
 }
 
diff --git a/garden-service/src/commands/call.ts b/garden-service/src/commands/call.ts
index ed63d62052..38bd57860d 100644
--- a/garden-service/src/commands/call.ts
+++ b/garden-service/src/commands/call.ts
@@ -24,7 +24,7 @@ import dedent = require("dedent")
 
 const callArgs = {
   serviceAndPath: new StringParameter({
-    help: "The name of the service(s) to call followed by the ingress path (e.g. my-container/somepath).",
+    help: "The name(s) of the service(s) to call followed by the ingress path (e.g. my-container/somepath).",
     required: true,
   }),
 }
@@ -36,7 +36,7 @@ export class CallCommand extends Command<Args> {
   help = "Call a service ingress endpoint."
 
   description = dedent`
-    This command resolves the deployed ingress endpoint for the given service and path, calls the given endpoint and
+    Resolves the deployed ingress endpoint for the given service and path, calls the given endpoint and
     outputs the result.
 
     Examples:
diff --git a/garden-service/src/commands/create/module.ts b/garden-service/src/commands/create/module.ts
index 8183ffedfc..51c62ca1e0 100644
--- a/garden-service/src/commands/create/module.ts
+++ b/garden-service/src/commands/create/module.ts
@@ -28,7 +28,7 @@ import { ensureDir } from "fs-extra"
 
 const createModuleOptions = {
   name: new StringParameter({
-    help: "Assigns a custom name to the module. (Defaults to name of the current directory.)",
+    help: "Assigns a custom name to the module (defaults to name of the current directory)",
   }),
   type: new ChoicesParameter({
     help: "Type of module.",
@@ -38,7 +38,7 @@ const createModuleOptions = {
 
 const createModuleArguments = {
   "module-dir": new StringParameter({
-    help: "Directory of the module. (Defaults to current directory.)",
+    help: "Directory of the module (defaults to current directory).",
   }),
 }
 
@@ -56,8 +56,6 @@ export class CreateModuleCommand extends Command<Args, Opts> {
   help = "Creates a new Garden module."
 
   description = dedent`
-    Creates a new Garden module of the given type
-
     Examples:
 
         garden create module # creates a new module in the current directory (module name defaults to directory name)
diff --git a/garden-service/src/commands/create/project.ts b/garden-service/src/commands/create/project.ts
index 5d86a1459a..a78c694d34 100644
--- a/garden-service/src/commands/create/project.ts
+++ b/garden-service/src/commands/create/project.ts
@@ -37,16 +37,16 @@ import { projectSchema } from "../../config/project"
 
 const createProjectOptions = {
   "module-dirs": new PathsParameter({
-    help: "Relative path to modules directory. Use comma as a separator to specify multiple directories",
+    help: "Relative path to modules directory. Use comma as a separator to specify multiple directories.",
   }),
   name: new StringParameter({
-    help: "Assigns a custom name to the project. (Defaults to name of the current directory.)",
+    help: "Assigns a custom name to the project (defaults to name of the current directory).",
   }),
 }
 
 const createProjectArguments = {
   "project-dir": new StringParameter({
-    help: "Directory of the project. (Defaults to current directory.)",
+    help: "Directory of the project (defaults to current directory).",
   }),
 }
 
@@ -67,7 +67,7 @@ export class CreateProjectCommand extends Command<Args, Opts> {
   help = "Creates a new Garden project."
 
   description = dedent`
-    The 'create project' command walks the user through setting up a new Garden project and
+    Walks the user through setting up a new Garden project and
     generates scaffolding based on user input.
 
     Examples:
@@ -75,8 +75,8 @@ export class CreateProjectCommand extends Command<Args, Opts> {
         garden create project # creates a new Garden project in the current directory (project name defaults to
         directory name)
         garden create project my-project # creates a new Garden project in my-project directory
-        garden create project --module-dirs=path/to/modules1,path/to/modules2
-        # creates a new Garden project and looks for pre-existing modules in the modules1 and modules2 directories
+        garden create project --module-dirs=path/to/modules-a,path/to/modules-b
+        # creates a new Garden project and looks for pre-existing modules in the modules-a and modules-b directories
         garden create project --name my-project
         # creates a new Garden project in the current directory and names it my-project
   `
diff --git a/garden-service/src/commands/delete.ts b/garden-service/src/commands/delete.ts
index c9d367b381..98abd442ba 100644
--- a/garden-service/src/commands/delete.ts
+++ b/garden-service/src/commands/delete.ts
@@ -105,7 +105,7 @@ export class DeleteEnvironmentCommand extends Command {
 
 const deleteServiceArgs = {
   service: new StringsParameter({
-    help: "The name of the service(s) to delete. Use comma as separator to specify multiple services.",
+    help: "The name(s) of the service(s) to delete. Use comma as a separator to specify multiple services.",
     required: true,
   }),
 }
diff --git a/garden-service/src/commands/deploy.ts b/garden-service/src/commands/deploy.ts
index 68a065bbfc..7386706852 100644
--- a/garden-service/src/commands/deploy.ts
+++ b/garden-service/src/commands/deploy.ts
@@ -7,6 +7,8 @@
  */
 
 import deline = require("deline")
+import dedent = require("dedent")
+
 import {
   BooleanParameter,
   Command,
@@ -24,7 +26,7 @@ import { getNames } from "../util/util"
 const deployArgs = {
   service: new StringsParameter({
     help: deline`The name(s) of the service(s) to deploy (skip to deploy all services).
-      Use comma as separator to specify multiple services.`,
+      Use comma as a separator to specify multiple services.`,
   }),
 }
 
@@ -34,7 +36,7 @@ const deployOpts = {
   watch: new BooleanParameter({ help: "Watch for changes in module(s) and auto-deploy.", alias: "w" }),
   "hot-reload": new StringsParameter({
     help: deline`The name(s) of the service(s) to deploy with hot reloading enabled.
-      Use comma as separator to specify multiple services. When this option is used,
+      Use comma as a separator to specify multiple services. When this option is used,
       the command is run in watch mode (i.e. implicitly assumes the --watch/-w flag).
     `,
   }),
@@ -47,7 +49,7 @@ export class DeployCommand extends Command<Args, Opts> {
   name = "deploy"
   help = "Deploy service(s) to your environment."
 
-  description = `
+  description = dedent`
     Deploys all or specified services, taking into account service dependency order.
     Also builds modules and dependencies if needed.
 
diff --git a/garden-service/src/commands/dev.ts b/garden-service/src/commands/dev.ts
index 43b5b140dc..d508758f14 100644
--- a/garden-service/src/commands/dev.ts
+++ b/garden-service/src/commands/dev.ts
@@ -8,6 +8,7 @@
 
 import * as Bluebird from "bluebird"
 import deline = require("deline")
+import dedent = require("dedent")
 import chalk from "chalk"
 import { readFile } from "fs-extra"
 import { flatten } from "lodash"
@@ -38,7 +39,7 @@ const devArgs = {}
 const devOpts = {
   "hot-reload": new StringsParameter({
     help: deline`The name(s) of the service(s) to deploy with hot reloading enabled.
-      Use comma as separator to specify multiple services.
+      Use comma as a separator to specify multiple services.
     `}),
 }
 
@@ -50,7 +51,7 @@ export class DevCommand extends Command<Args, Opts> {
   name = "dev"
   help = "Starts the garden development console."
 
-  description = `
+  description = dedent`
     The Garden dev console is a combination of the \`build\`, \`deploy\` and \`test\` commands.
     It builds, deploys and tests all your modules and services, and re-builds, re-deploys and re-tests
     as you modify the code.
diff --git a/garden-service/src/commands/link/module.ts b/garden-service/src/commands/link/module.ts
index a576c3d113..f5349df542 100644
--- a/garden-service/src/commands/link/module.ts
+++ b/garden-service/src/commands/link/module.ts
@@ -47,7 +47,7 @@ export class LinkModuleCommand extends Command<Args> {
   description = dedent`
     After linking a remote module, Garden will read the source from the module's local directory instead of from
     the remote URL. Garden can only link modules that have a remote source,
-    i.e. modules that specifiy a repositoryUrl in their garden.yml config file.
+    i.e. modules that specifiy a \`repositoryUrl\` in their \`garden.yml\` config file.
 
     Examples:
 
diff --git a/garden-service/src/commands/link/source.ts b/garden-service/src/commands/link/source.ts
index da31980f0d..c668291916 100644
--- a/garden-service/src/commands/link/source.ts
+++ b/garden-service/src/commands/link/source.ts
@@ -42,7 +42,7 @@ export class LinkSourceCommand extends Command<Args> {
   description = dedent`
     After linking a remote source, Garden will read it from its local directory instead of
     from the remote URL. Garden can only link remote sources that have been declared in the project
-    level garden.yml config.
+    level \`garden.yml\` config.
 
     Examples:
 
diff --git a/garden-service/src/commands/logs.ts b/garden-service/src/commands/logs.ts
index 1b38758cff..352b0b3302 100644
--- a/garden-service/src/commands/logs.ts
+++ b/garden-service/src/commands/logs.ts
@@ -23,8 +23,8 @@ import dedent = require("dedent")
 
 const logsArgs = {
   service: new StringsParameter({
-    help: "The name of the service(s) to logs (skip to logs all services). " +
-      "Use comma as separator to specify multiple services.",
+    help: "The name(s) of the service(s) to log (skip to log all services). " +
+      "Use comma as a separator to specify multiple services.",
   }),
 }
 
diff --git a/garden-service/src/commands/publish.ts b/garden-service/src/commands/publish.ts
index d3e6ed5657..d97f863820 100644
--- a/garden-service/src/commands/publish.ts
+++ b/garden-service/src/commands/publish.ts
@@ -23,8 +23,8 @@ import dedent = require("dedent")
 
 const publishArgs = {
   module: new StringsParameter({
-    help: "The name of the module(s) to publish (skip to publish all modules). " +
-      "Use comma as separator to specify multiple modules.",
+    help: "The name(s) of the module(s) to publish (skip to publish all modules). " +
+      "Use comma as a separator to specify multiple modules.",
   }),
 }
 
diff --git a/garden-service/src/commands/run/service.ts b/garden-service/src/commands/run/service.ts
index f2b097be7d..7b08e6a143 100644
--- a/garden-service/src/commands/run/service.ts
+++ b/garden-service/src/commands/run/service.ts
@@ -22,13 +22,13 @@ import { prepareRuntimeContext } from "../../types/service"
 
 const runArgs = {
   service: new StringParameter({
-    help: "The service to run",
+    help: "The service to run.",
     required: true,
   }),
 }
 
 const runOpts = {
-  "force-build": new BooleanParameter({ help: "Force rebuild of module" }),
+  "force-build": new BooleanParameter({ help: "Force rebuild of module." }),
 }
 
 type Args = typeof runArgs
@@ -36,7 +36,7 @@ type Opts = typeof runOpts
 
 export class RunServiceCommand extends Command<Args, Opts> {
   name = "service"
-  help = "Run an ad-hoc instance of the specified service"
+  help = "Run an ad-hoc instance of the specified service."
 
   description = dedent`
     This can be useful for debugging or ad-hoc experimentation with services.
diff --git a/garden-service/src/commands/test.ts b/garden-service/src/commands/test.ts
index 8072f7d7b9..058f75cd33 100644
--- a/garden-service/src/commands/test.ts
+++ b/garden-service/src/commands/test.ts
@@ -8,6 +8,8 @@
 
 import * as Bluebird from "bluebird"
 import { flatten } from "lodash"
+import dedent = require("dedent")
+
 import {
   BooleanParameter,
   Command,
@@ -25,8 +27,8 @@ import { computeAutoReloadDependants, withDependants } from "../watch"
 
 const testArgs = {
   module: new StringsParameter({
-    help: "The name of the module(s) to deploy (skip to test all modules). " +
-      "Use comma as separator to specify multiple modules.",
+    help: "The name(s) of the module(s) to test (skip to test all modules). " +
+      "Use comma as a separator to specify multiple modules.",
   }),
 }
 
@@ -47,20 +49,20 @@ export class TestCommand extends Command<Args, Opts> {
   name = "test"
   help = "Test all or specified modules."
 
-  description = `
+  description = dedent`
     Runs all or specified tests defined in the project. Also builds modules and dependencies,
-    and deploy service dependencies if needed.
+    and deploys service dependencies if needed.
 
     Optionally stays running and automatically re-runs tests if their module source
     (or their dependencies' sources) change.
 
     Examples:
 
-        garden test              # run all tests in the project
-        garden test my-module    # run all tests in the my-module module
-        garden test -n integ     # run all tests with the name 'integ' in the project
-        garden test --force      # force tests to be re-run, even if they're already run successfully
-        garden test --watch      # watch for changes to code
+        garden test               # run all tests in the project
+        garden test my-module     # run all tests in the my-module module
+        garden test --name integ  # run all tests with the name 'integ' in the project
+        garden test --force       # force tests to be re-run, even if they've already run successfully
+        garden test --watch       # watch for changes to code
   `
 
   arguments = testArgs
diff --git a/garden-service/src/commands/unlink/module.ts b/garden-service/src/commands/unlink/module.ts
index 929f04b4ac..e7b059610c 100644
--- a/garden-service/src/commands/unlink/module.ts
+++ b/garden-service/src/commands/unlink/module.ts
@@ -23,7 +23,7 @@ import {
 
 const unlinkModuleArguments = {
   module: new StringsParameter({
-    help: "Name of the module(s) to unlink. Use comma separator to specify multiple modules.",
+    help: "The name(s) of the module(s) to unlink. Use comma as a separator to specify multiple modules.",
   }),
 }
 
@@ -49,8 +49,8 @@ export class UnlinkModuleCommand extends Command<Args, Opts> {
 
     Examples:
 
-        garden unlink module my-module # unlinks my-module
-        garden unlink module --all # unlink all modules
+        garden unlink module my-module  # unlinks my-module
+        garden unlink module --all      # unlink all modules
   `
 
   async action({ garden, args, opts }: CommandParams<Args, Opts>): Promise<CommandResult<LinkedSource[]>> {
diff --git a/garden-service/src/commands/unlink/source.ts b/garden-service/src/commands/unlink/source.ts
index 8b68bf434d..7a609ce512 100644
--- a/garden-service/src/commands/unlink/source.ts
+++ b/garden-service/src/commands/unlink/source.ts
@@ -23,7 +23,7 @@ import {
 
 const unlinkSourceArguments = {
   source: new StringsParameter({
-    help: "Name of the source(s) to unlink. Use comma separator to specify multiple sources.",
+    help: "The name(s) of the source(s) to unlink. Use comma as a separator to specify multiple sources.",
   }),
 }
 
@@ -49,8 +49,8 @@ export class UnlinkSourceCommand extends Command<Args, Opts> {
 
     Examples:
 
-        garden unlink source my-source # unlinks my-source
-        garden unlink source --all # unlinks all sources
+        garden unlink source my-source  # unlinks my-source
+        garden unlink source --all      # unlinks all sources
   `
 
   async action({ garden, args, opts }: CommandParams<Args, Opts>): Promise<CommandResult<LinkedSource[]>> {
diff --git a/garden-service/src/commands/update-remote/modules.ts b/garden-service/src/commands/update-remote/modules.ts
index a377ca259a..9c9a718f39 100644
--- a/garden-service/src/commands/update-remote/modules.ts
+++ b/garden-service/src/commands/update-remote/modules.ts
@@ -23,7 +23,7 @@ import { hasRemoteSource } from "../../util/ext-source-util"
 
 const updateRemoteModulesArguments = {
   module: new StringsParameter({
-    help: "Name of the remote module(s) to update. Use comma separator to specify multiple modules.",
+    help: "The name(s) of the remote module(s) to update. Use comma as a separator to specify multiple modules.",
   }),
 }
 
@@ -35,8 +35,8 @@ export class UpdateRemoteModulesCommand extends Command<Args> {
   arguments = updateRemoteModulesArguments
 
   description = dedent`
-    Remote modules are modules that have a repositoryUrl field
-    in their garden.yml config that points to a remote repository.
+    Updates remote modules, i.e. modules that have a \`repositoryUrl\` field
+    in their \`garden.yml\` config that points to a remote repository.
 
     Examples:
 
diff --git a/garden-service/src/commands/update-remote/sources.ts b/garden-service/src/commands/update-remote/sources.ts
index 247e983507..4bdd9b42e6 100644
--- a/garden-service/src/commands/update-remote/sources.ts
+++ b/garden-service/src/commands/update-remote/sources.ts
@@ -22,7 +22,7 @@ import { SourceConfig } from "../../config/project"
 
 const updateRemoteSourcesArguments = {
   source: new StringsParameter({
-    help: "Name of the remote source(s) to update. Use comma separator to specify multiple sources.",
+    help: "The name(s) of the remote source(s) to update. Use comma as a separator to specify multiple sources.",
   }),
 }
 
@@ -34,11 +34,11 @@ export class UpdateRemoteSourcesCommand extends Command<Args> {
   arguments = updateRemoteSourcesArguments
 
   description = dedent`
-    Update the remote sources declared in the project config.
+    Updates the remote sources declared in the project level \`garden.yml\` config file.
 
     Examples:
 
-        garden update-remote sources            # update all remote sources in the project config
+        garden update-remote sources            # update all remote sources
         garden update-remote sources my-source  # update remote source my-source
   `
 
diff --git a/garden-service/src/docs/templates/commands.hbs b/garden-service/src/docs/templates/commands.hbs
index 37bd9b60cf..cd6f36a263 100644
--- a/garden-service/src/docs/templates/commands.hbs
+++ b/garden-service/src/docs/templates/commands.hbs
@@ -2,7 +2,7 @@
 
 Below is a list of Garden CLI commands and usage information.
 
-The commands should be run in a Garden project root, and are always scoped to that project.
+The commands should be run in a Garden project, and are always scoped to that project.
 
 Note: You can get a list of commands in the CLI by running `garden -h/--help`,
 and detailed help for each command using `garden <command> -h/--help`

From de5e4a58e0d5cf33f45208e164e6b4231d67a85a Mon Sep 17 00:00:00 2001
From: Thorarinn Sigurdsson <thorarinnsigurdsson@gmail.com>
Date: Wed, 31 Oct 2018 15:28:53 +0100
Subject: [PATCH 4/4] fix(docs): tweaks to config file reference docs

---
 docs/reference/command-reference.md      |   8 +-
 docs/reference/config-files-reference.md | 100 +++++++++++------------
 garden-service/src/config/common.ts      |  10 +--
 garden-service/src/config/module.ts      |  12 +--
 garden-service/src/config/project.ts     |   8 +-
 garden-service/src/config/test.ts        |   2 +-
 garden-service/src/plugins/container.ts  |  19 +++--
 garden-service/src/types/service.ts      |   4 +-
 8 files changed, 81 insertions(+), 82 deletions(-)

diff --git a/docs/reference/command-reference.md b/docs/reference/command-reference.md
index 069f5c74eb..371e7e1268 100644
--- a/docs/reference/command-reference.md
+++ b/docs/reference/command-reference.md
@@ -55,7 +55,7 @@ Examples:
 
 Call a service ingress endpoint.
 
-This command resolves the deployed ingress endpoint for the given service and path, calls the given endpoint and
+Resolves the deployed ingress endpoint for the given service and path, calls the given endpoint and
 outputs the result.
 
 Examples:
@@ -79,7 +79,7 @@ Note: Currently only supports simple GET requests for HTTP/HTTPS ingresses.
 
 Creates a new Garden project.
 
-This command walks the user through setting up a new Garden project and
+Walks the user through setting up a new Garden project and
 generates scaffolding based on user input.
 
 Examples:
@@ -656,7 +656,7 @@ Examples:
 
 Update remote sources.
 
-This command updates the remote sources declared in the project level `garden.yml` config file.
+Updates the remote sources declared in the project level `garden.yml` config file.
 
 Examples:
 
@@ -677,7 +677,7 @@ Examples:
 
 Update remote modules.
 
-This command updates remote modules, i.e. modules that have a `repositoryUrl` field
+Updates remote modules, i.e. modules that have a `repositoryUrl` field
 in their `garden.yml` config that points to a remote repository.
 
 Examples:
diff --git a/docs/reference/config-files-reference.md b/docs/reference/config-files-reference.md
index 72837052cc..cc01907339 100644
--- a/docs/reference/config-files-reference.md
+++ b/docs/reference/config-files-reference.md
@@ -35,11 +35,11 @@ module:
 
   description:
 
-  # A remote respository URL. Currently only supports git servers. Must contain a hash part
+  # A remote repository URL. Currently only supports git servers. Must contain a hash suffix
   # pointing to a specific branch or tag, with the format: <git remote url>#<branch|tag>
   #
-  # Garden will import the repository source code into this module, but read the config from
-  # the local garden.yml file
+  # Garden will import the repository source code into this module, but read the module's
+  # config from the local garden.yml file.
   #
   # Example: "git+https://github.com/org/repo.git#v2.0"
   #
@@ -55,16 +55,16 @@ module:
   variables: 
     {}
 
-  # Set to false to disable pushing this module to remote registries.
+  # When false, disables pushing this module to remote registries.
   #
   # Optional.
   allowPublish: true
 
-  # Specify how to build the module. Note that plugins may specify additional keys on this object.
+  # Specify how to build the module. Note that plugins may define additional keys on this object.
   #
   # Optional.
   build: 
-    # The command to run inside the module directory to perform the build.
+    # The command to run inside the module's directory to perform the build.
     #
     # Example:
     #   - npm
@@ -82,7 +82,7 @@ module:
     #
     # Optional.
     dependencies: 
-      - # Module name to build ahead of this module
+      - # Module name to build ahead of this module.
         #
         # Required.
         name:
@@ -103,7 +103,7 @@ module:
             # Optional.
             target:
 
-# The configuration for a Garden project. This should be specified in the garden.yml file in your
+# Configuration for a Garden project. This should be specified in the garden.yml file in your
 # project root.
 #
 # Optional.
@@ -120,8 +120,8 @@ project:
   # Optional.
   defaultEnvironment:
 
-  # Default environment settings, that are inherited (but can be overridden) by each configured
-  # environment
+  # Default environment settings. These are inherited (but can be overridden) by each configured
+  # environment.
   #
   # Example:
   #   providers: []
@@ -134,7 +134,7 @@ project:
     #
     # Optional.
     providers: 
-      - # The name of the provider plugin to configure.
+      - # The name of the provider plugin to use.
         #
         # Example: "local-kubernetes"
         #
@@ -162,7 +162,7 @@ project:
       #
       # Optional.
       providers: 
-        - # The name of the provider plugin to configure.
+        - # The name of the provider plugin to use.
           #
           # Example: "local-kubernetes"
           #
@@ -176,13 +176,13 @@ project:
         {}
 
       # Valid RFC1035/RFC1123 (DNS) label (may contain lowercase letters, numbers and dashes, must
-      # start with a letter,and cannot end with a dash) and additionally cannot contain
-      # consecutive dashes or be longer than 63 characters.
+      # start with a letter, and cannot end with a dash) and additionally cannot contain
+      # consecutive dashes, or be longer than 63 characters.
       #
       # Required.
       name:
 
-  # A list of remote sources to import into project
+  # A list of remote sources to import into project.
   #
   # Optional.
   sources: 
@@ -191,7 +191,7 @@ project:
       # Required.
       name:
 
-      # A remote respository URL. Currently only supports git servers. Must contain a hash part
+      # A remote repository URL. Currently only supports git servers. Must contain a hash suffix
       # pointing to a specific branch or tag, with the format: <git remote url>#<branch|tag>
       #
       # Example: "git+https://github.com/org/repo.git#v2.0"
@@ -226,11 +226,11 @@ module:
 
   description:
 
-  # A remote respository URL. Currently only supports git servers. Must contain a hash part
+  # A remote repository URL. Currently only supports git servers. Must contain a hash suffix
   # pointing to a specific branch or tag, with the format: <git remote url>#<branch|tag>
   #
-  # Garden will import the repository source code into this module, but read the config from
-  # the local garden.yml file
+  # Garden will import the repository source code into this module, but read the module's
+  # config from the local garden.yml file.
   #
   # Example: "git+https://github.com/org/repo.git#v2.0"
   #
@@ -246,16 +246,16 @@ module:
   variables: 
     {}
 
-  # Set to false to disable pushing this module to remote registries.
+  # When false, disables pushing this module to remote registries.
   #
   # Optional.
   allowPublish: true
 
-  # Specify how to build the module. Note that plugins may specify additional keys on this object.
+  # Specify how to build the module. Note that plugins may define additional keys on this object.
   #
   # Optional.
   build: 
-    # The command to run inside the module directory to perform the build.
+    # The command to run inside the module's directory to perform the build.
     #
     # Example:
     #   - npm
@@ -273,7 +273,7 @@ module:
     #
     # Optional.
     dependencies: 
-      - # Module name to build ahead of this module
+      - # Module name to build ahead of this module.
         #
         # Required.
         name:
@@ -313,7 +313,7 @@ module:
       # Required.
       name:
 
-      # The names of services that must be running before the test is run.
+      # Names of the services that must be running before the test is run.
       #
       # Optional.
       dependencies: 
@@ -362,11 +362,11 @@ module:
 
   description:
 
-  # A remote respository URL. Currently only supports git servers. Must contain a hash part
+  # A remote repository URL. Currently only supports git servers. Must contain a hash suffix
   # pointing to a specific branch or tag, with the format: <git remote url>#<branch|tag>
   #
-  # Garden will import the repository source code into this module, but read the config from
-  # the local garden.yml file
+  # Garden will import the repository source code into this module, but read the module's
+  # config from the local garden.yml file.
   #
   # Example: "git+https://github.com/org/repo.git#v2.0"
   #
@@ -382,16 +382,16 @@ module:
   variables: 
     {}
 
-  # Set to false to disable pushing this module to remote registries.
+  # When false, disables pushing this module to remote registries.
   #
   # Optional.
   allowPublish: true
 
-  # Specify how to build the module. Note that plugins may specify additional keys on this object.
+  # Specify how to build the module. Note that plugins may define additional keys on this object.
   #
   # Optional.
   build: 
-    # The command to run inside the module directory to perform the build.
+    # The command to run inside the module's directory to perform the build.
     #
     # Example:
     #   - npm
@@ -409,7 +409,7 @@ module:
     #
     # Optional.
     dependencies: 
-      - # Module name to build ahead of this module
+      - # Module name to build ahead of this module.
         #
         # Required.
         name:
@@ -430,16 +430,16 @@ module:
             # Optional.
             target:
 
-  # Specify build arguments when building the container image.
+  # Specify build arguments to use when building the container image.
   #
   # Optional.
   buildArgs: 
     {}
 
-  # Specify the image name for the container. Should be a valid docker image identifier. If
-  # specified and the module does not contain a Dockerfile, this image will be used to deploy the
-  # container services. If specified and the module does contain a Dockerfile, this identifier is
-  # used when pushing the built image.
+  # Specify the image name for the container. Should be a valid Docker image identifier. If
+  # specified and the module does not contain a Dockerfile, this image will be used to deploy
+  # services for this module. If specified and the module does contain a Dockerfile, this
+  # identifier is used when pushing the built image.
   #
   # Optional.
   image:
@@ -449,7 +449,7 @@ module:
   # Optional.
   dockerfile:
 
-  # List of services to deploy from this container module.
+  # The list of services to deploy from this container module.
   #
   # Optional.
   services: 
@@ -457,8 +457,8 @@ module:
     #
     # Optional.
     - # Valid RFC1035/RFC1123 (DNS) label (may contain lowercase letters, numbers and dashes, must
-      # start with a letter,and cannot end with a dash) and additionally cannot contain
-      # consecutive dashes or be longer than 63 characters.
+      # start with a letter, and cannot end with a dash) and additionally cannot contain
+      # consecutive dashes, or be longer than 63 characters.
       #
       # Required.
       name:
@@ -468,13 +468,13 @@ module:
       # Optional.
       dependencies: 
         # Valid RFC1035/RFC1123 (DNS) label (may contain lowercase letters, numbers and dashes,
-        # must start with a letter,and cannot end with a dash) and additionally cannot contain
-        # consecutive dashes or be longer than 63 characters.
+        # must start with a letter, and cannot end with a dash) and additionally cannot contain
+        # consecutive dashes, or be longer than 63 characters.
         #
         # Optional.
         -
 
-      # Key/value map, keys must be valid identifiers.
+      # Key/value map. Keys must be valid identifiers.
       #
       # Optional.
       outputs: 
@@ -500,8 +500,7 @@ module:
       # Optional.
       ingresses: 
         - # The hostname that should route to this service. Defaults to the default hostname
-          # configured
-          # in the provider configuration.
+          # configured in the provider configuration.
           #
           # Note that if you're developing locally you may need to add this hostname to your hosts
           # file.
@@ -530,7 +529,7 @@ module:
       #
       # Optional.
       healthCheck: 
-        # Set this to check the service's health by making an HTTP request
+        # Set this to check the service's health by making an HTTP request.
         #
         # Optional.
         httpGet: 
@@ -559,8 +558,7 @@ module:
         tcpPort:
 
       # If this module uses the `hotReload` field, the container will be run with these arguments
-      # instead of those in `command` while a Garden command with the -w (watch) flag, or `garden
-      # dev`, is running.
+      # instead of those in `command` when the service is deployed with hot reloading enabled.
       #
       # Optional.
       hotReloadCommand: 
@@ -573,7 +571,7 @@ module:
         #
         # Required.
         - # The name of the port (used when referencing the port elsewhere in the service
-          # configuration.
+          # configuration).
           #
           # Required.
           name:
@@ -624,7 +622,7 @@ module:
       # Required.
       name:
 
-      # The names of services that must be running before the test is run.
+      # Names of the services that must be running before the test is run.
       #
       # Optional.
       dependencies: 
@@ -651,8 +649,8 @@ module:
   # When this field is used, the files or directories specified within are automatically synced
   # into the running container when they're modified. Additionally, any of this module's services
   # that define a `hotReloadCommand` will be run with that command instead of the one specified in
-  # their `command` field. This behavior is only active while a Garden command with the -w (watch)
-  # flag, or `garden dev`, is running.
+  # their `command` field. Services are only deployed with hot reloading enabled when their names
+  # are passed to the `--hot-reload` option in a call to the `deploy` or `dev` command.
   #
   # Optional.
   hotReload: 
diff --git a/garden-service/src/config/common.ts b/garden-service/src/config/common.ts
index 6f98d71da9..f00101ac85 100644
--- a/garden-service/src/config/common.ts
+++ b/garden-service/src/config/common.ts
@@ -37,8 +37,8 @@ export const joiIdentifier = () => Joi.string()
   .regex(identifierRegex)
   .max(63)
   .description(
-    "Valid RFC1035/RFC1123 (DNS) label (may contain lowercase letters, numbers and dashes, must start with a letter," +
-    "and cannot end with a dash) and additionally cannot contain consecutive dashes or be longer than 63 characters.",
+    "Valid RFC1035/RFC1123 (DNS) label (may contain lowercase letters, numbers and dashes, must start with a letter, " +
+    "and cannot end with a dash) and additionally cannot contain consecutive dashes, or be longer than 63 characters.",
   )
 
 export const joiStringMap = (valueSchema: JoiObject) => Joi
@@ -56,13 +56,13 @@ export const joiUserIdentifier = () => Joi.string()
 export const joiIdentifierMap = (valueSchema: JoiObject) => Joi
   .object().pattern(identifierRegex, valueSchema)
   .default(() => ({}), "{}")
-  .description("Key/value map, keys must be valid identifiers.")
+  .description("Key/value map. Keys must be valid identifiers.")
 
 export const joiVariables = () => Joi
   .object().pattern(/[\w\d]+/i, joiPrimitive())
   .default(() => ({}), "{}")
   .unknown(false)
-  .description("Key/value map, keys may contain letters and numbers, and values must be primitives.")
+  .description("Key/value map. Keys may contain letters and numbers, and values must be primitives.")
 
 export const joiEnvVarName = () => Joi
   .string().regex(envVarRegex)
@@ -96,7 +96,7 @@ export const joiRepositoryUrl = () => Joi
     ],
   })
   .description(
-    "A remote respository URL. Currently only supports git servers. Must contain a hash part" +
+    "A remote repository URL. Currently only supports git servers. Must contain a hash suffix" +
     " pointing to a specific branch or tag, with the format: <git remote url>#<branch|tag>",
   )
   .example("git+https://github.com/org/repo.git#v2.0")
diff --git a/garden-service/src/config/module.ts b/garden-service/src/config/module.ts
index a5e13b6f45..53fcda94b6 100644
--- a/garden-service/src/config/module.ts
+++ b/garden-service/src/config/module.ts
@@ -44,7 +44,7 @@ export interface BuildDependencyConfig {
 
 export const buildDependencySchema = Joi.object().keys({
   name: joiIdentifier().required()
-    .description("Module name to build ahead of this module"),
+    .description("Module name to build ahead of this module."),
   plugin: joiIdentifier()
     .meta({ internal: true })
     .description("The name of plugin that provides the build dependency."),
@@ -85,26 +85,26 @@ export const baseModuleSpecSchema = Joi.object()
       .description(
         dedent`${joiRepositoryUrl().describe().description}
 
-        Garden will import the repository source code into this module, but read the config from
-        the local garden.yml file`,
+        Garden will import the repository source code into this module, but read the module's
+        config from the local garden.yml file.`,
       ),
     variables: joiVariables()
       .description("Variables that this module can reference and expose as environment variables.")
       .example({ "my-variable": "some-value" }),
     allowPublish: Joi.boolean()
       .default(true)
-      .description("Set to false to disable pushing this module to remote registries."),
+      .description("When false, disables pushing this module to remote registries."),
     build: Joi.object().keys({
       // TODO: move this out of base spec
       command: joiArray(Joi.string())
-        .description("The command to run inside the module directory to perform the build.")
+        .description("The command to run inside the module's directory to perform the build.")
         .example(["npm", "run", "build"]),
       dependencies: joiArray(buildDependencySchema)
         .description("A list of modules that must be built before this module is built.")
         .example([{ name: "some-other-module-name" }]),
     })
       .default(() => ({ dependencies: [] }), "{}")
-      .description("Specify how to build the module. Note that plugins may specify additional keys on this object."),
+      .description("Specify how to build the module. Note that plugins may define additional keys on this object."),
   })
   .required()
   .unknown(true)
diff --git a/garden-service/src/config/project.ts b/garden-service/src/config/project.ts
index f2ca5426db..537b022877 100644
--- a/garden-service/src/config/project.ts
+++ b/garden-service/src/config/project.ts
@@ -24,7 +24,7 @@ export interface ProviderConfig {
 export const providerConfigBaseSchema = Joi.object()
   .keys({
     name: joiIdentifier().required()
-      .description("The name of the provider plugin to configure.")
+      .description("The name of the provider plugin to use.")
       .example("local-kubernetes"),
   })
   .unknown(true)
@@ -79,7 +79,7 @@ export const projectSourceSchema = Joi.object()
 
 export const projectSourcesSchema = joiArray(projectSourceSchema)
   .unique("name")
-  .description("A list of remote sources to import into project")
+  .description("A list of remote sources to import into project.")
 
 export interface ProjectConfig {
   name: string
@@ -125,7 +125,7 @@ export const projectSchema = Joi.object()
       .default(() => environmentDefaults, safeDump(environmentDefaults))
       .example(environmentDefaults)
       .description(
-        "Default environment settings, that are inherited (but can be overridden) by each configured environment",
+        "Default environment settings. These are inherited (but can be overridden) by each configured environment.",
       ),
     environments: joiArray(environmentConfigSchema.keys({ name: joiIdentifier().required() }))
       .unique("name")
@@ -136,7 +136,7 @@ export const projectSchema = Joi.object()
   })
   .required()
   .description(
-    "The configuration for a Garden project. This should be specified in the garden.yml file in your project root.",
+    "Configuration for a Garden project. This should be specified in the garden.yml file in your project root.",
   )
 
 // this is used for default handlers in the action handler
diff --git a/garden-service/src/config/test.ts b/garden-service/src/config/test.ts
index 9235b6e5a5..4a34ff9bdc 100644
--- a/garden-service/src/config/test.ts
+++ b/garden-service/src/config/test.ts
@@ -26,7 +26,7 @@ export const baseTestSpecSchema = Joi.object()
       .required()
       .description("The name of the test."),
     dependencies: joiArray(Joi.string())
-      .description("The names of services that must be running before the test is run."),
+      .description("Names of the services that must be running before the test is run."),
     timeout: Joi.number()
       .allow(null)
       .default(null)
diff --git a/garden-service/src/plugins/container.ts b/garden-service/src/plugins/container.ts
index 977a844848..ac9d091dfb 100644
--- a/garden-service/src/plugins/container.ts
+++ b/garden-service/src/plugins/container.ts
@@ -121,7 +121,8 @@ const hotReloadConfigSchema = Joi.object()
     When this field is used, the files or directories specified within are automatically synced into the
     running container when they're modified. Additionally, any of this module's services that define a
     \`hotReloadCommand\` will be run with that command instead of the one specified in their \`command\` field.
-    This behavior is only active while a Garden command with the -w (watch) flag, or \`garden dev\`, is running.`)
+    Services are only deployed with hot reloading enabled when their names are passed to the \`--hot-reload\` option
+    in a call to the \`deploy\` or \`dev\` command.`)
 
 export type ContainerServiceConfig = ServiceConfig<ContainerServiceSpec>
 
@@ -149,7 +150,7 @@ const healthCheckSchema = Joi.object()
           .description("The name of the port where the service's health check endpoint should be available."),
         scheme: Joi.string().allow("HTTP", "HTTPS").default("HTTP"),
       })
-      .description("Set this to check the service's health by making an HTTP request"),
+      .description("Set this to check the service's health by making an HTTP request."),
     command: Joi.array().items(Joi.string())
       .description("Set this to check the service's health by running a command in its container."),
     tcpPort: Joi.string()
@@ -160,7 +161,7 @@ const portSchema = Joi.object()
   .keys({
     name: joiIdentifier()
       .required()
-      .description("The name of the port (used when referencing the port elsewhere in the service configuration."),
+      .description("The name of the port (used when referencing the port elsewhere in the service configuration)."),
     protocol: Joi.string()
       .allow("TCP", "UDP")
       .default(DEFAULT_PORT_PROTOCOL)
@@ -208,8 +209,8 @@ const serviceSchema = baseServiceSchema
     hotReloadCommand: Joi.array().items(Joi.string())
       .description(deline`
         If this module uses the \`hotReload\` field, the container will be run with
-        these arguments instead of those in \`command\` while a Garden command with the -w
-        (watch) flag, or \`garden dev\`, is running.`,
+        these arguments instead of those in \`command\` when the service is deployed
+        with hot reloading enabled.`,
       ),
     ports: joiArray(portSchema)
       .unique("name")
@@ -271,18 +272,18 @@ export const containerModuleSpecSchema = Joi.object()
     buildArgs: Joi.object()
       .pattern(/.+/, joiPrimitive())
       .default(() => ({}), "{}")
-      .description("Specify build arguments when building the container image."),
+      .description("Specify build arguments to use when building the container image."),
     // TODO: validate the image name format
     image: Joi.string()
       .description(deline`
-        Specify the image name for the container. Should be a valid docker image identifier. If specified and
-        the module does not contain a Dockerfile, this image will be used to deploy the container services.
+        Specify the image name for the container. Should be a valid Docker image identifier. If specified and
+        the module does not contain a Dockerfile, this image will be used to deploy services for this module.
         If specified and the module does contain a Dockerfile, this identifier is used when pushing the built image.`),
     dockerfile: Joi.string().uri(<any>{ relativeOnly: true })
       .description("POSIX-style name of Dockerfile, relative to project root. Defaults to $MODULE_ROOT/Dockerfile."),
     services: joiArray(serviceSchema)
       .unique("name")
-      .description("List of services to deploy from this container module."),
+      .description("The list of services to deploy from this container module."),
     tests: joiArray(containerTestSchema)
       .description("A list of tests to run in the module."),
     hotReload: hotReloadConfigSchema,
diff --git a/garden-service/src/types/service.ts b/garden-service/src/types/service.ts
index 5205d4caad..9029f0a1c2 100644
--- a/garden-service/src/types/service.ts
+++ b/garden-service/src/types/service.ts
@@ -64,8 +64,8 @@ export interface ServiceIngress extends ServiceIngressSpec {
 export const ingressHostnameSchema = Joi.string()
   .hostname()
   .description(dedent`
-    The hostname that should route to this service. Defaults to the default hostname configured
-    in the provider configuration.
+    The hostname that should route to this service. Defaults to the default hostname
+    configured in the provider configuration.
 
     Note that if you're developing locally you may need to add this hostname to your hosts file.
   `)