respond to comments

website/source/docs/jobops/inspecting.html.md

@@ -9,7 +9,7 @@ description: |-
 # Inspecting state
 
 Once a job is submitted, the next step is to ensure it is running. This section
-will assume we have submitted a job with the name "example".
+will assume we have submitted a job with the name _example_.
 
 To get a high-level over view of our job we can use the [`nomad status`
 command](/docs/commands/status.html). This command will display the list of
@@ -54,8 +54,9 @@ progress. When Nomad can not place all the desired allocations, it creates a
 blocked evaluation that waits for more resources to become available. We can use
 the [`eval-status` command](/docs/commands/eval-status.html) to examine any
 evaluation in more detail. For the most part this should never be necessary but
-can be useful to see why everything was not placed. For example if we run it on
-the evaluation that had placement failures we see:
+can be useful to see why all of a job's allocations were not placed. For
+example if we run it on the _example_ job, which had a placement failure
+according to the above output, we see:
 
 ```
 nomad eval-status 8e38e6cf
@@ -104,7 +105,7 @@ Time                   Type        Description
 06/28/16 15:37:44 UTC  Received    Task received by client
 ```
 
-In the above example we forced killed the docker container so that we could see
+In the above example we forced killed the Docker container so that we could see
 in the event history that Nomad detected the failure and restarted the
 allocation.
 
@@ -141,7 +142,8 @@ Time                   Type            Description
 Not all failures are this easily debuggable. If the `alloc-status` command shows
 many restarts occuring as in the example below, it is a good hint that the error
 is occuring at the application level during start up. These failres can be
-debugged by looking at logs which is covered [here](/docs/jobops/logs.html).
+debugged by looking at logs which is covered in the [Nomad Job Logging
+documentation](/docs/jobops/logs.html).
 
 ```
 $ nomad alloc-status e6b6

website/source/docs/jobops/logs.html.md

@@ -9,7 +9,7 @@ description: |-
 # Accessing Logs
 
 Accessing applications logs is critical when debugging issues, performance
-problems or even for checking the application is starting correctly. To make
+problems or even for verifying the application is starting correctly. To make
 this as simple as possible, Nomad provides both a CLI tool and an API for
 accessing application logs and data files.
 
@@ -21,7 +21,7 @@ $ nomad init
 Example job file written to example.nomad
 ```
 
-This job will start a redis instance in a docker container. We can run it now:
+This job will start a redis instance in a Docker container. We can run it now:
 
 ```
 $ nomad run example.nomad
@@ -36,10 +36,11 @@ We can grab the allocation ID from above and use the [`nomad fs`
 command](/docs/commands/fs.html) to access the applications logs. Logs are
 stored under the following directory structure:
 `alloc/logs/<task-name>.<stdout/stderr>.<index>`. Nomad has built in log
-rotation as defined [here](TODO). The index is a monotonically increasing
-number starting at zero and incremented each time the log is rotated.
+rotation, documented in the [Jobspec](/docs/jobspec/index.html#log_rotation).
+The index is a monotonically increasing number starting at zero and incremented
+each time the log is rotated.
 
-Thus to access the stdout we can issue the below command:
+Thus to access the `stdout` we can issue the below command:
 
 ```
 $ nomad fs c3c58508 alloc/logs/redis.stdout.0
@@ -68,7 +69,7 @@ $ nomad fs c3c58508 alloc/logs/redis.stdout.0
  1:M 28 Jun 19:49:30.505 * The server is now ready to accept connections on port 6379
 ```
 
-Replacing stdout for stderr would display the respective stderr output.
+Replacing `stdout` for `stderr` would display the respective `stderr` output.
 
 While this works well for quickly accessing logs, we recommend running a
 log-shipper for long term storage of logs. In many cases this will not be needed

website/source/docs/jobops/resources.html.md

@@ -65,8 +65,8 @@ While single point in time resource usage measurements are useful, it is often
 more useful to graph resource usage over time to better understand and estimate
 resource usage. Nomad supports outputting resource data to statsite and statsd
 and is the recommended way of monitoring resources. For more information about
-outputing telemetry see [here](/docs/agent/telemetry.html).
+outputing telemetry see the [Telemetry documentation](/docs/agent/telemetry.html).
 
 For more advanced use cases, the resource usage data may also be accessed via
-the client's HTTP API. See the documentation
-[here](/docs/http/client-allocation-stats.html)
+the client's HTTP API. See the documentation of the Client's
+[Allocation HTTP API](/docs/http/client-allocation-stats.html)

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

@@ -13,4 +13,4 @@ each other. As such, Nomad has built in support for registering services and
 health checks with [Consul](http://consul.io).
 
 For more details on using service discovery with your application, see
-[here](/docs/jobspec/servicediscovery.html).
+the [Service Discovery documentation](/docs/jobspec/servicediscovery.html).

website/source/docs/jobops/taskconfig.html.md

@@ -21,7 +21,7 @@ configuration via command-line arguments that will not change.
 Nomad has many [drivers](/docs/drivers/index.html) and most support passing
 arguments to their tasks via the `args` parameter. To configure these simply
 provide the appropriate arguments. Below is an example using the [`docker`
-driver](/docs/drivers/docker.html) to launch memcached and set its thread count
+driver](/docs/drivers/docker.html) to launch `memcached(8)` and set its thread count
 to 4, increase log verbosity, as well as assign the correct port and address
 bindings using interpolation:
 

website/source/docs/jobops/updating.html.md

@@ -65,7 +65,7 @@ potentially invalid.
 Here we can see that Nomad will destroy the 3 existing tasks and create 3
 replacements but it will occur with a rolling update with a stagger of `10s`.
 For more details on the update block, see
-[here](/docs/jobspec/index.html#update).
+the [Jobspec documentation](/docs/jobspec/index.html#update).
 
 ## Blue-green and Canaries
 
@@ -171,4 +171,4 @@ connections and conduct any other cleanup that is necessary. Certain
 applications take longer to drain than others and as such Nomad lets the job
 file specify how long to wait inbetween signaling the application to exit and
 forcefully killing it. This is configurable via the `kill_timeout`. More details
-can be seen [here](/docs/jobspec/index.html#kill_timeout).
+can be seen in the [Jobspec documentation](/docs/jobspec/index.html#kill_timeout).

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

@@ -277,7 +277,7 @@ The `task` object supports the following keys:
   the timeout a kill signal is sent (on Unix `SIGKILL`).
 
 * `logs` - Logs allows configuring log rotation for the `stdout` and `stderr`
-  buffers of a Task. See the log rotation reference below for more details.
+  buffers of a Task. See the [log rotation section](#log_rotation) for more details.
 
 * `artifact` - Defines an artifact to be downloaded before the task is run. This
   can be provided multiple times to define additional artifacts to download. See
@@ -395,6 +395,8 @@ The `constraint` object supports the following keys:
     redundant since when placed at the job level, the constraint will be applied
     to all task groups.
 
+<a id="log_rotation"></a>
+
 ### Log Rotation
 
 The `logs` object configures the log rotation policy for a task's `stdout` and