Clarify all_at_once parameter

Fixes https://github.com/hashicorp/nomad/issues/3125

website/source/api/json-jobs.html.md

@@ -130,9 +130,11 @@ their default values if any for each type of object.
 
 The `Job` object supports the following keys:
 
-- `AllAtOnce` - Controls if the entire set of tasks in the job must
-  be placed atomically or if they can be scheduled incrementally.
-  This should only be used for special circumstances. Defaults to `false`.
+- `AllAtOnce` - Controls whether the scheduler can make partial placements if
+  optimistic scheduling resulted in an oversubscribed node. This does not
+  control whether all allocations for the job, where all would be the desired
+  count for each task group, must be placed atomically. This should only be
+  used for special circumstances. Defaults to `false`.
 
 - `Constraints` - A list to define additional constraints where a job can be
   run. See the constraint reference for more details.

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

@@ -26,8 +26,6 @@ of one or many tasks.
 
 ```hcl
 job "docs" {
-  all_at_once = true
-
   constraint {
     # ...
   }
@@ -70,6 +68,12 @@ job "docs" {
   must be placed atomically or if they can be scheduled incrementally. This
   should only be used for special circumstances.
 
+- `all_at_once` `(bool: false)` - Controls whether the scheduler can make
+  partial placements if optimistic scheduling resulted in an oversubscribed
+  node. This does not control whether all allocations for the job, where all
+  would be the desired count for each task group, must be placed atomically.
+  This should only be used for special circumstances.
+
 - `constraint` <code>([Constraint][constraint]: nil)</code> -
   This can be provided multiple times to define additional constraints. See the
   [Nomad constraint reference](/docs/job-specification/constraint.html) for more