Minor documentation edits for grammar and clarity

These are things I noticed as I read through the documentation.
There are a couple of minor substantive corrections as well.

website/source/docs/agent/config.html.md

@@ -263,10 +263,10 @@ integration and are entirely optional.
     `host:port`. Defaults to `127.0.0.1:8500`, which is the same as the Consul
     default HTTP address.
 
-  * `token`: Token is used to provide a per-request ACL token. This options
+  * `token`: Token is used to provide a per-request ACL token. This option
     overrides the Consul Agent's default token.
 
-  * `auth`: The auth information to use for http access to the Consul Agent
+  * `auth`: The auth information to use for HTTP access to the Consul Agent
     given as `username:password`.
 
   * `ssl`: This boolean option sets the transport scheme to talk to the Consul
@@ -440,9 +440,9 @@ configured on server nodes.
     `max_kill_timeout` is used. This is to prevent a user being able to set an
     unreasonable timeout. If unset, a default is used.
 <a id="reserved"></a>
-  * `reserved`: `reserved` is used to reserve a portion of the nodes resources
+  * `reserved`: `reserved` is used to reserve a portion of the node's resources
     from being used by Nomad when placing tasks.  It can be used to target
-    a certain capacity usage for the node. For example, 20% of the nodes CPU
+    a certain capacity usage for the node. For example, 20% of the node's CPU
     could be reserved to target a CPU utilization of 80%. The block has the
     following format:
 
@@ -458,7 +458,7 @@ configured on server nodes.
     * `cpu`: `cpu` is given as MHz to reserve.
     * `memory`: `memory` is given as MB to reserve.
     * `disk`: `disk` is given as MB to reserve.
-    * `reserved_ports`: `reserved_ports` is a comma separated list of ports
+    * `reserved_ports`: `reserved_ports` is a comma-separated list of ports
       to reserve on all fingerprinted network devices. Ranges can be
       specified by using a hyphen separated the two inclusive ends.
 
@@ -469,13 +469,13 @@ Client, but rather the set of options that configure the Client and not the
 drivers. To find the options supported by an individual driver, see the drivers
 documentation [here](/docs/drivers/index.html)
 
-* `driver.whitelist`: A comma separated list of whitelisted drivers (e.g.
+* `driver.whitelist`: A comma-separated list of whitelisted drivers (e.g.
   "docker,qemu"). If specified, drivers not in the whitelist will be disabled.
   If the whitelist is empty, all drivers are fingerprinted and enabled where
   applicable.
 
 *   `env.blacklist`: Nomad passes the host environment variables to `exec`,
-    `raw_exec` and `java` tasks. `env.blacklist` is a comma separated list of
+    `raw_exec` and `java` tasks. `env.blacklist` is a comma-separated list of
     environment variable keys not to pass to these tasks. If specified, the
     defaults are overridden. The following are the default:
 
@@ -500,14 +500,14 @@ documentation [here](/docs/drivers/index.html)
     * `qemu`
     * `java`
 
-* `fingerprint.whitelist`: A comma separated list of whitelisted fingerprinters.
+* `fingerprint.whitelist`: A comma-separated list of whitelisted fingerprinters.
   If specified, fingerprinters not in the whitelist will be disabled. If the
   whitelist is empty, all fingerprinters are used.
 
 ### <a id="chroot_env_map"></a>Client ChrootEnv Map
 
 Drivers based on [Isolated Fork/Exec](/docs/drivers/exec.html) implement file
-system isolation using chroot on Linux.  The `chroot_env` map allows the chroot
+system isolation using chroot on Linux. The `chroot_env` map allows the chroot
 environment to be configured using source paths on the host operating system.
 The mapping format is: `source_path -> dest_path`.
 
@@ -534,7 +534,7 @@ environment with the most commonly used parts of the operating system. See
 A subset of the available Nomad agent configuration can optionally be passed in
 via CLI arguments. The `agent` command accepts the following arguments:
 
-* `alloc-dir=<path>`: Equivalent to the Client [alloc_dir](#alloc_dir) config
+* `-alloc-dir=<path>`: Equivalent to the Client [alloc_dir](#alloc_dir) config
    option.
 * `-atlas=<infrastructure>`: Equivalent to the Atlas
   [infrastructure](#infrastructure) config option.
@@ -555,9 +555,9 @@ via CLI arguments. The `agent` command accepts the following arguments:
   be specified multiple times to specify multiple agents to join.
 * `-log-level=<level>`: Equivalent to the [log_level](#log_level) config option.
 * `-meta=<key=value>`: Equivalent to the Client [meta](#meta) config option.
-* `-network-interface<interface>`: Equivalent to the Client
+* `-network-interface=<interface>`: Equivalent to the Client
    [network_interface](#network_interface) config option.
-* `-network-speed<MBits>`: Equivalent to the Client
+* `-network-speed=<MBits>`: Equivalent to the Client
   [network_speed](#network_speed) config option.
 * `-node=<name>`: Equivalent to the [name](#name) config option.
 * `-node-class=<class>`: Equivalent to the Client [node_class](#node_class)

website/source/docs/agent/index.html.md

@@ -92,13 +92,13 @@ respective signals.
 When gracefully exiting, clients will update their status to terminal on
 the servers so that tasks can be migrated to healthy agents. Servers
 will notify their intention to leave the cluster which allows them to
-leave the [consensus quorum](/docs/internals/consensus.html).
+leave the [consensus](/docs/internals/consensus.html) peer set.
 
 It is especially important that a server node be allowed to leave gracefully
 so that there will be a minimal impact on availability as the server leaves
-the consensus quorum. If a server does not gracefully leave, and will not
+the consensus peer set. If a server does not gracefully leave, and will not
 return into service, the [`server-force-leave` command](/docs/commands/server-force-leave.html)
-should be used to eject it from the consensus quorum.
+should be used to eject it from the consensus peer set.
 
 ## Lifecycle
 
@@ -135,5 +135,5 @@ to the entire cluster, meaning all nodes will eventually be aware of each other.
 
 When a server _leaves_, it specifies its intent to do so, and the cluster marks that
 node as having _left_. If the server has _left_, replication to it will stop and it
-is removed as a member of the consensus quorum. If the server has _failed_, replication
+is removed from the consensus peer set. If the server has _failed_, replication
 will attempt to make progress to recover from a software or network failure.

website/source/docs/commands/eval-status.html.md.erb

@@ -14,7 +14,7 @@ evaluation. In the case an evaluation could not place all the requested
 allocations, this command can be used to determine the failure reasons.
 
 Optionally, it can also be invoked in a monitor mode to track an outstanding
-evaluation. In this mode, ogs will be output describing state changes to the
+evaluation. In this mode, logs will be output describing state changes to the
 evaluation or its associated allocations. The monitor will exit when the
 evaluation reaches a terminal state.
 

website/source/docs/commands/fs.html.md.erb

@@ -26,8 +26,8 @@ client. The following functionalities are available - `cat`, `tail`, `ls` and
 nomad fs [options] <alloc-id> <path>
 ```
 
-This command accepts a path and single allocation ID unless the `-job` flag is
-specified, in which case an allocation is chosen for the given job.  The path is
+This command accepts a single allocation ID (unless the `-job` flag is specified,
+in which case an allocation is chosen from the given job) and a path. The path is
 relative to the root of the allocation directory.  The path is optional and it
 defaults to `/` of the allocation directory.
 
@@ -41,14 +41,14 @@ defaults to `/` of the allocation directory.
 
 * `-verbose`: Display verbose output.
 
-* `-job`: Use a random allocation from the specified job, prefering a running
+* `-job`: Use a random allocation from the specified job, preferring a running
 allocation.
 
 * `-stat`: Show stat information instead of displaying the file, or listing the
 directory.
 
 * `-f`: Causes the output to not stop when the end of the file is reached, but
-rather to wait for additional output. 
+rather to wait for additional output.
 
 * `-tail`: Show the files contents with offsets relative to the end of the file.
 If no offset is given, -n is defaulted to 10.

website/source/docs/commands/logs.html.md.erb

@@ -16,7 +16,7 @@ The `logs` command displays the log of a given task.
 nomad logs [options] <alloc-id> <task>
 ```
 
-This commands streams the logs of the given task in the allocation. If the
+This command streams the logs of the given task in the allocation. If the
 allocation is only running a single task, the task name can be omitted.
 Optionally, the `-job` option may be used in which case a random allocation from
 the given job will be chosen.
@@ -35,7 +35,7 @@ the given job will be chosen.
 allocation.
 
 * `-f`: Causes the output to not stop when the end of the logs are reached, but
-rather to wait for additional output. 
+rather to wait for additional output.
 
 * `-tail`: Show the logs contents with offsets relative to the end of the logs.
 If no offset is given, -n is defaulted to 10.

website/source/docs/commands/plan.html.md.erb

@@ -24,8 +24,8 @@ containing a [HCL job specification](/docs/jobspec/index.html). This file
 will be read and the job checked for any problems. If the
 supplied path is "-", the jobfile is read from STDIN. Otherwise it is read
 from the file at the supplied path or downloaded and read from URL specified.
-Nomad downloads jobfile using [`go-getter`](https://github.com/hashicorp/go-getter)
-and support `go-getter` syntax.
+Nomad downloads the jobfile using [`go-getter`](https://github.com/hashicorp/go-getter)
+and supports `go-getter` syntax.
 
 Plan invokes a dry-run of the scheduler to determine the effects of submitting
 either a new or updated version of a job. The plan will not result in any

website/source/docs/commands/run.html.md.erb

@@ -23,8 +23,8 @@ containing a valid [job specification](/docs/jobspec/index.html). This file
 will be read and the job will be submitted to Nomad for scheduling. If the
 supplied path is "-", the jobfile is read from STDIN. Otherwise it is read
 from the file at the supplied path or downloaded and read from URL specified.
-Nomad downloads jobfile using [`go-getter`](https://github.com/hashicorp/go-getter)
-and support `go-getter` syntax.
+Nomad downloads the jobfile using [`go-getter`](https://github.com/hashicorp/go-getter)
+and supports `go-getter` syntax.
 
 By default, on successful job submission the run command will enter an
 interactive monitor and display log information detailing the scheduling

website/source/docs/commands/validate.html.md.erb

@@ -22,8 +22,8 @@ containing a [HCL job specification](/docs/jobspec/index.html). This file
 will be read and the job checked for any problems. If the
 supplied path is "-", the jobfile is read from STDIN. Otherwise it is read
 from the file at the supplied path or downloaded and read from URL specified.
-Nomad downloads jobfile using [`go-getter`](https://github.com/hashicorp/go-getter)
-and support `go-getter` syntax.
+Nomad downloads the jobfile using [`go-getter`](https://github.com/hashicorp/go-getter)
+and supports `go-getter` syntax.
 
 On successful validation, exit code 0 will be returned, otherwise an exit code
 of 1 indicates an error.

website/source/docs/drivers/docker.html.md

@@ -102,7 +102,7 @@ The `docker` driver supports the following configuration in the job spec:
 * `ipc_mode` - (Optional) The IPC mode to be used for the container. The default
   is `none` for a private IPC namespace. Other values are `host` for sharing
   the host IPC namespace or the name or id of an existing container. Note that
-  it is not possible to refer to Nomad started Docker containers since their
+  it is not possible to refer to Docker containers started by Nomad since their
   names are not known in advance. Note that setting this option also requires the
   Nomad agent to be configured to allow privileged containers.
 
@@ -339,11 +339,11 @@ The `docker` driver has the following [client configuration
 options](/docs/agent/config.html#options):
 
 * `docker.endpoint` - Defaults to `unix:///var/run/docker.sock`. You will need
-  to customize this if you use a non-standard socket (http or another
+  to customize this if you use a non-standard socket (HTTP or another
   location).
 
-* `docker.auth.config` - Allows an operator to specify a json file which is in
-  the dockercfg format containing authentication information for private registry.
+* `docker.auth.config` - Allows an operator to specify a JSON file which is in
+  the dockercfg format containing authentication information for a private registry.
 
 * `docker.tls.cert` - Path to the server's certificate file (`.pem`). Specify
   this along with `docker.tls.key` and `docker.tls.ca` to use a TLS client to
@@ -439,6 +439,7 @@ container does not exceed the amount of memory allocated to it, or it will be
 terminated or crash when it tries to malloc. A process can inspect its memory
 limit by reading `NOMAD_MEMORY_LIMIT`, but will need to track its own memory
 usage. Memory limit is expressed in megabytes so 1024 = 1Gb.
+HIO!!!
 
 ### IO
 

website/source/docs/drivers/exec.html.md

@@ -36,7 +36,7 @@ The `exec` driver supports the following configuration in the job spec:
   is downloaded from an [`artifact`](/docs/jobspec/index.html#artifact_doc), the
   path can be relative from the allocations's root directory.
 
-* `args` - (Optional) A list of arguments to the optional `command`. References
+* `args` - (Optional) A list of arguments to the `command`. References
   to environment variables or any [interpretable Nomad
   variables](/docs/jobspec/interpreted.html) will be interpreted before
   launching the task.

website/source/docs/drivers/java.html.md

@@ -34,7 +34,7 @@ The `java` driver supports the following configuration in the job spec:
   contains the Jar in a subfolder, the path will need to be the relative path
   (`subdir/from_archive/my.jar`).
 
-* `args` - (Optional) A list of arguments to the optional `command`. References
+* `args` - (Optional) A list of arguments to the Jar's main method. References
   to environment variables or any [interpretable Nomad
   variables](/docs/jobspec/interpreted.html) will be interpreted before
   launching the task.

website/source/docs/drivers/raw_exec.html.md

@@ -34,10 +34,10 @@ The `raw_exec` driver supports the following configuration in the job spec:
   is downloaded from an [`artifact`](/docs/jobspec/index.html#artifact_doc), the
   path can be relative from the allocations's root directory.
 
-* `args` - (Optional) A list of arguments to the optional `command`. References
+* `args` - (Optional) A list of arguments to the `command`. References
   to environment variables or any [interpretable Nomad
   variables](/docs/jobspec/interpreted.html) will be interpreted before
-  launching the task. For example:
+  launching the task.
 
 ## Examples
 

website/source/docs/faq.html.md

@@ -24,7 +24,7 @@ and [`disable_update_check`](/docs/agent/config.html#disable_update_check).
 Nomad makes use of a HashiCorp service called [SCADA](http://scada.hashicorp.com)
 (Supervisory Control And Data Acquisition). The SCADA system allows clients to maintain
 long-running connections to Atlas. Atlas can in turn provide auto-join facilities for
-Nomad agents (supervisory control) and an dashboard showing the state of the system (data acquisition).
+Nomad agents (supervisory control) and a dashboard showing the state of the system (data acquisition).
 
 Using the SCADA service is optional. SCADA is only enabled by opt-in.
 

website/source/docs/http/client-fs.html.md

@@ -192,7 +192,7 @@ allocation was placed.
 <dl>
   <dt>Description</dt>
   <dd>
-     Stream a tasks stdout/stderr logs.
+     Stream a task's stdout/stderr logs.
   </dd>
 
   <dt>Method</dt>

website/source/docs/http/job.html.md

@@ -532,9 +532,9 @@ region is used; another region can be specified using the `?region=` query param
       <li>
         <span class="param">Diff</span>
         A diff structure between the submitted job and the server side version.
-        The top-level object is a Job Diff which contains, Task Group Diffs
+        The top-level object is a Job Diff which contains Task Group Diffs,
         which in turn contain Task Diffs. Each of these objects then has Object
-        and Field Diff structures in-bedded.
+        and Field Diff structures embedded.
       </li>
       <li>
         <span class="param">NextPeriodicLaunch</span>

website/source/docs/install/index.html.md

@@ -25,8 +25,8 @@ Nomad is currently packaged as a zip file. We do not have any near term
 plans to provide system packages.
 
 Once the zip is downloaded, unzip it into any directory. The
-`nomad` binary inside is all that is necessary to run Nomad (or
-`nomad.exe` for Windows). Any additional files, if any, are not
+`nomad` (or `nomad.exe` for Windows) binary inside is all that is
+necessary to run Nomad. Any additional files, if any, are not
 required to run Nomad.
 
 Copy the binary to anywhere on your system. If you intend to access it

website/source/docs/jobspec/environment.html.md

@@ -96,7 +96,7 @@ the memory limit to inform how large your in-process cache should be, or to
 decide when to flush buffers to disk.
 
 Both CPU and memory are presented as integers. The unit for CPU limit is
-`1024 = 1Ghz`. The unit for memory is `1 = 1 megabytes`.
+`1024 = 1GHz`. The unit for memory is `1 = 1 megabyte`.
 
 Writing your applications to adjust to these values at runtime provides greater
 scheduling flexibility since you can adjust the resource allocations in your
@@ -128,17 +128,17 @@ Depending on the driver and operating system being targeted, the directories are
 made available in various ways. For example, on `docker` the directories are
 bound to the container, while on `exec` on Linux the directories are mounted into the
 chroot. Regardless of how the directories are made available, the path to the
-directories can be read through the following environment variables:
-`NOMAD_ALLOC_DIR` and `NOMAD_TASK_DIR`.
+directories can be read through the `NOMAD_ALLOC_DIR` and `NOMAD_TASK_DIR`
+environment variables.
 
 ## Meta
 
 The job specification also allows you to specify a `meta` block to supply arbitrary
 configuration to a task. This allows you to easily provide job-specific
 configuration even if you use the same executable unit in multiple jobs. These
-key-value pairs are passed through to the job as `NOMAD_META_<key>=<value>`,
-where `key` is UPPERCASED from the job specification.
+key-value pairs are passed through to the job as `NOMAD_META_<key>=<value>`
+environment variables, where `key` is UPPERCASED from the job specification.
 
-Currently there is no enforcement that the meta values be lowercase, but using
+Currently there is no enforcement that the meta keys be lowercase, but using
 multiple keys with the same uppercased representation will lead to undefined
 behavior.

website/source/docs/jobspec/index.html.md

@@ -410,7 +410,7 @@ The `constraint` object supports the following keys:
 
 * `version` - Specifies a version constraint against the attribute.
   This sets the operator to `version` and the `value` to what is
-  specified. This supports a comma separated list of constraints,
+  specified. This supports a comma-separated list of constraints,
   including the pessimistic operator. See the
   [go-version](https://github.com/hashicorp/go-version) repository
   for examples.

website/source/docs/jobspec/interpreted.html.md

@@ -7,7 +7,7 @@ description: |-
 ---
 # Interpreted Variables
 
-Nomad support interpreting two classes of variables, node attributes and runtime
+Nomad supports interpreting two classes of variables, node attributes and runtime
 environment variables. Node attributes are interpretable in constraints, task
 environment variables and certain driver fields. Runtime environment variables
 are not interpretable in constraints because they are only defined once the

website/source/docs/jobspec/json.html.md

@@ -321,15 +321,13 @@ The `Task` object supports the following keys:
   [Click here](/docs/jobspec/servicediscovery.html) to learn more about
   services. Below is the fields in the `Service` object:
 
-     * `Name`: Nomad automatically determines the name of a Task. By default the
-       name of a service is `$(job-name)-$(task-group)-$(task-name)`. Users can
-       explicitly name the service by specifying this option. If multiple
-       services are defined for a Task then only one task can have the default
-       name, all the services have to be explicitly named.  Users can add the
-       following to the service names: `${JOB}`, `${TASKGROUP}`, `${TASK}`,
-       `${BASE}`.  Nomad will replace them with the appropriate value of the
-       Job, Task Group, and Task names while registering the Job. `${BASE}`
-       expands to `${JOB}-${TASKGROUP}-${TASK}`.  Names must be adhere to
+     * `Name`: An explicit name for the Service. Nomad will replace `${JOB}`,
+       `${TASKGROUP}` and `${TASK}` by the name of the job, task group or task,
+       respectively. `${BASE}` expands to the equivalent of
+       `${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service.
+       Each service defined for a given task must have a distinct name, so if
+       a task has multiple services only one of them can use the default name
+       and the others must be explicitly named. Names must adhere to
        [RFC-1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are
        limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be
        less than 64 characters in length.
@@ -338,16 +336,15 @@ The `Task` object supports the following keys:
        interpolation is supported in tags.
 
      * `PortLabel`: `PortLabel` is an optional string and is used to associate
-       the port with the service.  If specified, the port label must match one
-       defined in the resources block.  This could be a label to either a
-       dynamic or a static port. If an incorrect port label is specified, Nomad
-       doesn't register the IP:Port with Consul.
+       a port with the service.  If specified, the port label must match one
+       defined in the resources block.  This could be a label of either a
+       dynamic or a static port.
 
      * `Checks`: `Checks` is an array of check objects. A check object defines a
        health check associated with the service. Nomad supports the `script`,
        `http` and `tcp` Consul Checks. Script checks are not supported for the
        qemu driver since the Nomad client doesn't have access to the file system
-       of a tasks using the Qemu driver.
+       of a task using the Qemu driver.
 
          * `Type`:  This indicates the check types supported by Nomad. Valid
            options are currently `script`, `http` and `tcp`.
@@ -366,7 +363,7 @@ The `Task` object supports the following keys:
            to add the relative URL of the health check endpoint.
 
          * `Protocol`: This indicates the protocol for the http checks. Valid
-           options are `http` and `https`. We default it to `http`
+           options are `http` and `https`. We default it to `http`.
 
          * `Command`: This is the command that the Nomad client runs for doing
            script based health check.

website/source/docs/jobspec/networking.html.md

@@ -10,7 +10,7 @@ description: |-
 
 When scheduling jobs in Nomad they are provisioned across your fleet of
 machines along with other jobs and services. Because you don't know in advance
-what host your job will be provisioned on, Nomad will provide your task with
+what host your job will be provisioned on, Nomad will provide your tasks with
 network configuration when they start up.
 
 Note that this document only applies to services that want to _listen_
@@ -109,7 +109,7 @@ The above example is for the Docker driver. The service is listening on port
 to this service.
 
 When the task is started, it is passed an additional environment variable named
-`NOMAD_HOST_PORT_http` which indicates the host port that the http service is
+`NOMAD_HOST_PORT_http` which indicates the host port that the HTTP service is
 bound to.
 
 Please refer to the [Docker](/docs/drivers/docker.html) and [QEMU](/docs/drivers/qemu.html) drivers for additional information.

website/source/docs/jobspec/schedulers.html.md

@@ -16,7 +16,7 @@ the differences between each of these schedulers.
 
 The `service` scheduler is designed for scheduling long lived services that
 should never go down. As such, the `service` scheduler ranks a large portion
-of the nodes that meet the jobs constraints and selects the optimal node to
+of the nodes that meet the job's constraints and selects the optimal node to
 place a task group on. The `service` scheduler uses a best fit scoring algorithm
 influenced by Google work on Borg. Ranking this larger set of candidate nodes
 increases scheduling time but provides greater guarantees about the optimality
@@ -28,7 +28,7 @@ Batch jobs are much less sensitive to short term performance fluctuations and
 are short lived, finishing in a few minutes to a few days. Although the `batch`
 scheduler is very similar to the `service` scheduler, it makes certain
 optimizations for the batch workload. The main distinction is that after finding
-the set of nodes that meet the jobs constraints it uses the power of two choices
+the set of nodes that meet the job's constraints it uses the power of two choices
 described in Berkeley's Sparrow scheduler to limit the number of nodes that are
 ranked.
 
@@ -41,6 +41,6 @@ that all registered `system` jobs will be re-evaluated and their tasks will be
 placed on the newly available nodes if the constraints are met.
 
 This scheduler type is extremely useful for deploying and managing tasks that
-should be present on every node in the cluster. Since these tasks are being
+should be present on every node in the cluster. Since these tasks are
 managed by Nomad, they can take advantage of job updating, rolling deploys,
 service discovery and more.

website/source/docs/jobspec/servicediscovery.html.md

@@ -25,14 +25,14 @@ To configure Consul integration please see the Agent's configuration
 
 ## Service Definition Syntax
 
-The service block in a Task definition defines a service which Nomad will
-register with Consul. Multiple service blocks are allowed in a Task definition,
-which allow registering multiple services for a Task that exposes multiple
+The service block in a task definition defines a service which Nomad will
+register with Consul. Multiple service blocks are allowed in a task definition,
+which allow registering multiple services for a task that exposes multiple
 ports.
 
 ### Example
 
-A brief example of a service definition in a Task
+A brief example of a service definition in a task
 
 ```hcl
 group "database" {
@@ -73,15 +73,13 @@ group "database" {
 }
 ```
 
-* `name`: Nomad automatically determines the name of a Task. By default the
-  name of a service is `$(job-name)-$(task-group)-$(task-name)`. Users can
-  explicitly name the service by specifying this option. If multiple services
-  are defined for a Task then only one task can have the default name, all
-  the services have to be explicitly named.  Users can add the following to
-  the service names: `${JOB}`, `${TASKGROUP}`, `${TASK}`, `${BASE}`.  Nomad
-  will replace them with the appropriate value of the Job, Task Group, and
-  Task names while registering the Job. `${BASE}` expands to
-  `${JOB}-${TASKGROUP}-${TASK}`.  Names must be adhere to
+* `Name`: An explicit name for the Service. Nomad will replace `${JOB}`,
+  `${TASKGROUP}` and `${TASK}` by the name of the job, task group or task,
+  respectively. `${BASE}` expands to the equivalent of
+  `${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service.
+  Each service defined for a given task must have a distinct name, so if
+  a task has multiple services only one of them can use the default name
+  and the others must be explicitly named. Names must adhere to
   [RFC-1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are
   limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be
   less than 64 characters in length.
@@ -89,16 +87,15 @@ group "database" {
 * `tags`: A list of tags associated with this Service. String interpolation is
   supported in tags.
 
-* `port`: `port` is optional and is used to associate the port with the service.
+* `port`: `port` is optional and is used to associate a port with the service.
   If specified, the port label must match one defined in the resources block.
-  This could be a label to either a dynamic or a static port. If an incorrect
-  port label is specified, Nomad doesn't register the IP:Port with Consul.
+  This could be a label of either a dynamic or a static port.
 
 * `check`: A check block defines a health check associated with the service.
   Multiple check blocks are allowed for a service. Nomad supports the `script`,
   `http` and `tcp` Consul Checks. Script checks are not supported for the qemu
   driver since the Nomad client doesn't have access to the file system of a
-  tasks using the Qemu driver.
+  task using the Qemu driver.
 
 ### Check Syntax
 
@@ -119,7 +116,7 @@ group "database" {
   of the health check endpoint.
 
 * `protocol`: This indicates the protocol for the http checks. Valid options
-  are `http` and `https`. We default it to `http`
+  are `http` and `https`. We default it to `http`.
 
 * `command`: This is the command that the Nomad client runs for doing script based
   health check.