docs(platform): tweak upgrade docs

Author: Kent Rancourt

docs/managing_deis/upgrading-deis.rst

@@ -63,37 +63,51 @@ Finally, update ``deisctl`` to the new version and reinstall:
     enable PROXY protocol for ports 80 and 443 on the ELB, add a ``TCP 443:443`` listener, and
     change existing targets and health checks from HTTP to TCP.
 
+Upgrade Deis clients
+^^^^^^^^^^^^^^^^^^^^
+As well as upgrading ``deisctl``, make sure to upgrade the :ref:`deis client <install-client>` to
+match the new version of Deis.
 
 Graceful Upgrade
 ----------------
 
 Alternatively, an experimental feature exists to provide the ability to perform a graceful upgrade. This process is
-available for version 1.9.0 moving foward and is intended to facilitate upgrades within a major version - upgrading
-between major versions is not supported. Unlike the in-place process above, this process keeps the platforms
-routers and publishers up during the upgrade process. This means that there should only be a maximum of around 1-2
-seconds of downtime while the routers boot up. Many times, there will be no downtime at all.
+available for version 1.9.0 moving foward and is intended to facilitate upgrades within a major version (for example,
+from 1.9.0 to 1.9.1 or 1.10.0). Upgrading between major versions is not supported (for example, from 1.9.0 to a
+future 2.0.0). Unlike the in-place process above, this process keeps the platform's routers and publishers up during
+the upgrade process. This means that there should only be a maximum of around 1-2 seconds of downtime while the
+routers boot up. Many times, there will be no downtime at all.
+
+.. note::
 
-Your loadbalancer configuration is the determining factor for how much downtime will occur during a successful upgrade.
-If your loadbalancer is configured to quickly reactivate failed hosts to its pool of active hosts, its quite possible to
-achieve zero downtime upgrades. If your loadbalancer is configured to more pessimistic, such as requiring multiple
-successful healthchecks before reactiving a node, then the chance for downtime increases. You should review your
-loadbalancers configuration to determine what to expect during the upgrade process.
+    Your loadbalancer configuration is the determining factor for how much downtime will occur during a successful upgrade.
+    If your loadbalancer is configured to quickly reactivate failed hosts to its pool of active hosts, its quite possible to
+    achieve zero downtime upgrades. If your loadbalancer is configured to be more pessimistic, such as requiring multiple
+    successful healthchecks before reactiving a node, then the chance for downtime increases. You should review your
+    loadbalancers configuration to determine what to expect during the upgrade process.
 
-The process involves two deisctl commands, upgrade-prep and upgrade-takeover in coordination with a few important commands.
+The process involves two ``deisctl`` subcommands, ``upgrade-prep`` and ``upgrade-takeover``, in coordination with a few other important commands.
 
-First, a new deisctl version should be installed to a temporary location, reflecting the desired version to upgrade
-to. Care should be taken not to overwrite the existing deisctl version.
+First, a new ``deisctl`` version should be installed to a temporary location, reflecting the desired version to upgrade
+to. Care should be taken not to overwrite the existing ``deisctl`` version.
 
 .. code-block:: console
 
     $ mkdir /tmp/upgrade
-    $ curl -sSL http://deis.io/deisctl/install.sh | sh -s 1.8.0 /tmp/upgrade
+    $ curl -sSL http://deis.io/deisctl/install.sh | sh -s 1.10.0 /tmp/upgrade
     $ /tmp/upgrade/deisctl --version  # should match the desired platform
-    1.8.0
+    1.10.0
     $ /tmp/upgrade/deisctl refresh-units
-    $ /tmp/upgrade/deisctl config platform set version=v1.8.0
+    $ /tmp/upgrade/deisctl config platform set version=v1.10.0
+
+.. note::
+
+    Deis version 1.10.0 does not exist at the time of this writing, but since
+    the upgrade feature is only available for upgrading from Deis version
+    1.9.0 and higher, the snippet above is a realistic portrayal of how
+    this feature can be used in the future.
 
-Now it is possible to prepare the cluster for the upgrade using the old deisctl binary. This command will shutdown
+Now it is possible to prepare the cluster for the upgrade using the old ``deisctl`` binary. This command will shutdown
 and uninstall all components of the cluster except the router and publisher. This means your services should still be
 serving traffic afterwords, but nothing else in the cluster will be functional.
 
@@ -108,15 +122,15 @@ replacing them one by one. Then the rest of the components are brought up. The e
 
     $ /tmp/upgrade/deisctl upgrade-takeover
 
-It is recommended to move the newer deisctl into /opt/bin once the procedure is complete.
+It is recommended to move the newer ``deisctl`` into ``/opt/bin`` once the procedure is complete.
 
 If the process were to fail, the old version can be restored manually by reinstalling and starting the old components.
 
 .. code-block:: console
 
     $ /tmp/upgrade/deisctl stop platform
     $ /tmp/upgrade/deisctl uninstall platform
-    $ /tmp/upgrade/deisctl config platform set version=v1.8.0
+    $ /tmp/upgrade/deisctl config platform set version=v1.9.0
     $ /opt/bin/deisctl refresh-units
     $ /opt/bin/deisctl install platform
     $ /opt/bin/deisctl start platform