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.
   `)