Address review comments

website/source/docs/job-specification/spread.html.md

@@ -3,7 +3,7 @@ layout: "docs"
 page_title: "spread Stanza - Job Specification"
 sidebar_current: "docs-job-specification-spread"
 description: |-
-  The "spread" stanza allows operators to configure desired target percentages for allocations according to node attributes or metadata.
+  The "spread" stanza is used to spread placements across a certain node attributes such as datacenter.
   Spread may be specified at the job, group, or task levels for ultimate flexibility.
   More than one spread stanza may be specified with relative weights between each.
 ---
@@ -23,19 +23,24 @@ description: |-
   </tr>
 </table>
 
-The `spread` stanza allows operators to specify target percentages of allocations according to
-specific node attributes or metadata. Spread may
-be expressed on [attributes][interpolation] or [client metadata][client-meta].
-Additionally spread may be specified at the [job][job], [group][group], or
-[task][task] levels for ultimate flexibility.
+The spread stanza allows operators to influence the placement of allocations in a task group.
+Operators can use spread to increase failure tolerance of their application.
+The operator can specify a node attribute such as datacenter, availability zone, or even rack
+in a physical datacenter to spread the allocations over. By default, when using spread the scheduler will attempt to place allocations equally
+among the available values of the given target.
 
-Nomad will use any defined spread criteria when computing node scores for placement.
-Nodes are scored acccording to how closely they match the desired target percentage defined in the
+Nodes are scored according to how closely they match the desired target percentage defined in the
 spread stanza. Spread scores are combined with other scoring factors such as bin packing.
 
 A job or task group can have more than one spread criteria, with weights to express relative preference.
 
-Spread criteria are treated as a soft preference by the Nomad scheduler. If no nodes match a given spread criteria, placement is still successful.
+Spread criteria are treated as a soft preference by the Nomad scheduler.
+If no nodes match a given spread criteria, placement is still successful.
+
+Spread may be expressed on [attributes][interpolation] or [client metadata][client-meta].
+Additionally, spread may be specified at the [job][job], [group][group], or
+[task][task] levels for ultimate flexibility.
+
 
 ## `spread` Parameters
 
@@ -48,7 +53,7 @@ Spread criteria are treated as a soft preference by the Nomad scheduler. If no n
    Nomad will spread allocations evenly across all values of the attribute.
 
 - `weight` `(integer:0)` - Specifies a weight for the spread stanza. The weight is used
-  during scoring and must be an integer between -100 to 100. Weights can be used
+  during scoring and must be an integer between 0 to 100. Weights can be used
   when there is more than one spread or affinity stanza to express relative preference across them.
 
 ## `target` Parameters
@@ -63,8 +68,9 @@ The following examples show different ways to use the `spread` stanza.
 
 ### Even Spread Across Data Center
 
-This example shows a spread stanza across the node's `datacenter` attribute. Allocations
-are placed evenly across all datacenters with this example.
+This example shows a spread stanza across the node's `datacenter` attribute. If we have
+two datacenters `us-east1` and `us-west1`, and a task group of `count = 10`,
+Nomad will attempt to place 5 allocations in each datacenter.
 
 ```hcl
 spread {
@@ -75,16 +81,36 @@ spread {
 
 ### Spread With Target Percentages
 
+This example shows a spread stanza that specifies one target percentage. If we
+have three datacenters `us-east1`, `us-east2` and `us-west1`, and a task group
+of `count = 10` Nomad will attempt to place place 5 of the allocations in "us-east1",
+and then spread the rest among the other two datacenters.
+
+```hcl
+spread {
+  attribute = "${node.datacenter}"
+  weight    = 100
+
+  target "us-east1" {
+    percent = 50
+  }
+}
+```
+
 This example shows a spread stanza that specifies target percentages for two
-different datacenters.
+different datacenters. If we have two datacenters `us-east1` and `us-west1`,
+and a task group of `count = 10`, Nomad will attempt to place 6 allocations
+in `us-east1` and 4 in `us-west1`.
 
 ```hcl
 spread {
   attribute = "${node.datacenter}"
   weight    = 100
+
   target "us-east1" {
     percent = 60
   }
+
   target "us-west1" {
       percent = 40
   }
@@ -93,7 +119,11 @@ spread {
 
 ### Spread Across Multiple Attributes
 
-This example shows spread stanzas with multiple attributes
+This example shows spread stanzas with multiple attributes. Consider a Nomad cluster
+where there are two datacenters `us-east1` and `us-west1`, and each datacenter has nodes
+with `${meta.rack}` being `r1` or `r2`. For the following spread stanza used on a job with `count=12`, Nomad
+will attempt to place 6 allocations in each datacenter. Within a datacenter, Nomad will
+attempt to place 3 allocations in nodes on rack `r1`, and 3 allocations in nodes on rack `r2`.
 
 ```hcl
 spread {
@@ -112,6 +142,4 @@ spread {
 [task]: /docs/job-specification/task.html "Nomad task Job Specification"
 [interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"
 [node-variables]: /docs/runtime/interpolation.html#node-variables- "Nomad interpolation-Node variables"
-[constraint]: /docs/job-specification/constraint.html "Nomad Constraint job Specification"
-
-
+[constraint]: /docs/job-specification/constraint.html "Nomad Constraint job Specification"
\ No newline at end of file