diff --git a/website/source/docs/upgrade/index.html.md b/website/source/docs/upgrade/index.html.md
index d45c8aee1..758f20a25 100644
--- a/website/source/docs/upgrade/index.html.md
+++ b/website/source/docs/upgrade/index.html.md
@@ -101,11 +101,11 @@ Use the same actions in step #2 above to confirm cluster health.
 ### 5. Upgrade clients
 
 Following the successful upgrade of the servers you can now update your
-clients using a similar process as the servers.  If you wish to gracefully
-move tasks on a client use the `nomad node drain <node-id>` command to
-gracefully migrate jobs to another client in the cluster.  The `node drain`
-command prevents new tasks from being allocated to the client and begins
-migrating existing allocations to another client.
+clients using a similar process as the servers.  You may either upgrade clients
+in-place or start new nodes on the new version. See the [Decommissioning Nodes
+guide](/guides/node-draining.html) for instructions on how to migrate running
+allocations from the old nodes to the new nodes with the [`nomad node
+drain`](/docs/commands/node/drain.html) command.
 
 ## Done!
 
diff --git a/website/source/docs/upgrade/upgrade-specific.html.md b/website/source/docs/upgrade/upgrade-specific.html.md
index dad0032eb..836c8166b 100644
--- a/website/source/docs/upgrade/upgrade-specific.html.md
+++ b/website/source/docs/upgrade/upgrade-specific.html.md
@@ -51,6 +51,22 @@ Raft Protocol versions supported by each Consul version:
 In order to enable all [Autopilot](/guides/cluster/autopilot.html) features, all servers
 in a Nomad cluster must be running with Raft protocol version 3 or later.
 
+### Node Draining Improvements
+
+Node draining via the [`node drain`][drain-cli] command or the [drain
+API][drain-api] has been substantially changed in Nomad 0.8. In Nomad 0.7.1 and
+earlier draining a node would immediately stop all allocations on the node
+being drained. Nomad 0.8 now supports a [`migrate`][migrate] stanza in job
+specifications to control how many allocations may be migrated at once and the
+default will be used for existing jobs.
+
+The `drain` command now blocks until the drain completes. To get the Nomad
+0.7.1 and earlier drain behavior use the command: `nomad node drain -enable
+-force -detach <node-id>`
+
+See the [`migrate` stanza documentation][migrate] and [Decommissioning Nodes
+guide](/guides/node-draining.html) for details.
+
 ### Periods in Environment Variable Names No Longer Escaped
 
 *Applications which expect periods in environment variable names to be replaced
@@ -210,3 +226,7 @@ draining the node so no tasks are running on it. This can be verified by running
 `nomad node status <node-id>` and verify there are no tasks in the `running`
 state. Once that is done the client can be killed, the `data_dir` should be
 deleted and then Nomad 0.3.0 can be launched.
+
+[drain-api]: /api/nodes.html#drain-node
+[drain-cli]: /docs/commands/node/drain.html
+[migrate]: /docs/job-specification/migrate.html