doc/cephadm: improving "Monitoring the Upgrade"

This PR improves the section "Monitoring the Upgrade"
in the "Upgrading Ceph" chapter of the cephadm documentation.

This PR introduces a couple of section breaks with signposting
information in their titles, and rewrites some sentences in order
to reduce the cognitive load of the reader.

Signed-off-by: Zac Dover <zac.dover@gmail.com>
(cherry picked from commit 2dcdef0d43fb269447b5a00c8c29dc508919768d)

diff --git a/doc/cephadm/upgrade.rst b/doc/cephadm/upgrade.rst
index c1bbff7e413e7e7d314d5025834f1b13e7dd9f6c..4e3e657bf43c889ae9fdc25ebc0acff22a190dd6 100644 (file)
--- a/doc/cephadm/upgrade.rst
+++ b/doc/cephadm/upgrade.rst
@@ -41,28 +41,32 @@ For example, to upgrade to v15.2.1:
 Monitoring the upgrade
 ======================
 
-Determine whether an upgrade is in process and what version the cluster is
-upgrading to with:
+Determine (1) whether an upgrade is in progress and (2) which version the
+cluster is upgrading to by running the following command:
 
 .. prompt:: bash #
 
   ceph orch upgrade status
 
-While the upgrade is underway, you will see a progress bar in the ceph
-status output. For example:
+Watching the progress bar during a Ceph upgrade
+-----------------------------------------------
 
-.. prompt:: bash #
+During the upgrade, a progress bar is visible in the ceph status output. It
+looks like this:
 
-  ceph -s
+.. code-block:: console
 
-Expected output::
+  # ceph -s
 
   [...]
     progress:
       Upgrade to docker.io/ceph/ceph:v15.2.1 (00h 20m 12s)
         [=======.....................] (time remaining: 01h 43m 31s)
 
-You can also watch the cephadm log by running the following command:
+Watching the cephadm log during an upgrade
+------------------------------------------
+
+Watch the cephadm log by running the following command:
 
 .. prompt:: bash #