doc: README.md - improve "Tshooting" and "Tips & Tricks"

Improve the formatting and English language in the sections
"Troubleshooting" and "Tips and Tricks", and move those sections to a
place where they don't interrupt the flow of the vstart cluster
installation instructions. Some of the strings in "Tips and Tricks" are
not yet unambiguous sentences that will make sense to the uninitiated,
but this PR represents a step in that direction.

This PR is part of a series of PRs meant to preserve the integrity of
the README.md file after some recent additions that break the flow of
the document.

This PR follows https://github.com/ceph/ceph/pull/61226 and
https://github.com/ceph/ceph/pull/61221.

Signed-off-by: Zac Dover <zac.dover@proton.me>

diff --git a/README.md b/README.md
index a3fdfada623c3e0819f5fb5ca36ace33a3258394..f8fcf35e8b787c74278f6ae71aa680674b155c2b 100644 (file)
--- a/README.md
+++ b/README.md
@@ -127,31 +127,7 @@ To build Ceph, follow this procedure:
 
        ninja install
 
-## Tips and Tricks
-
-   * Use "debug builds" only when needed. Debugging builds are helpful for
-     development, but they can slow down performance. Use
-     `-DCMAKE_BUILD_TYPE=Release` when debugging isn't necessary.
-   * Enable Selective Daemons when testing specific components. Don't start
-     unnecessary daemons.
-   * Preserve Existing Data skip cluster reinitialization between tests by
-     using the `-n` flag.
-
-##  Troubleshooting     
- 
-    * Cluster Fails to Start: Look for errors in the logs under the `out/`
-      directory.
-    * OSD Crashes: Check the OSD logs for errors.
-    * Cluster in a `Health Error` State: Run the `ceph status` command to
-      identify the issue.
-    * RocksDB Errors: Look for RocksDB-related errors in the OSD logs.
     
-    To manage a vstart cluster, stop daemons using `./stop.sh` and start them with ./vstart.sh --daemon osd.${ID} [--nodaemonize]. 
-    Restart by stopping and restarting daemons, ensuring no stale sockets. 
-    For RocksDB performance tracking, set `export ROCKSDB_PERF=true` and start the cluster with `./vstart.sh -n -d -x --bluestore`. 
-    Build with `vstart-base` using debug flags in cmake, compile, and deploy via `./vstart.sh -d -n --bluestore`.
-    To containerize, generate configurations with `vstart.sh`, and deploy with Docker, mapping directories and configuring the network.
-    Manage containers using `docker run`, `stop`, and `rm`. For detailed setups, consult the Ceph-Container repository.
 
  
 ### CMake Options
@@ -204,6 +180,36 @@ The diagnostic colors will be visible when the following command is run:
 Other available values for `DIAGNOSTICS_COLOR` are `auto` (default) and
 `never`.
 
+## Tips and Tricks
+
+   * Use "debug builds" only when needed. Debugging builds are helpful for
+     development, but they can slow down performance. Use
+     `-DCMAKE_BUILD_TYPE=Release` when debugging isn't necessary.
+   * Enable Selective Daemons when testing specific components. Don't start
+     unnecessary daemons.
+   * Preserve Existing Data skip cluster reinitialization between tests by
+     using the `-n` flag.
+   * To manage a vstart cluster, stop daemons using `./stop.sh` and start them
+     with `./vstart.sh --daemon osd.${ID} [--nodaemonize]`. 
+   * Restart the sockets by stopping and restarting the daemons associated with
+     them. This ensures that there are no stale sockets in the cluster.
+   * To track RocksDB performance, set `export ROCKSDB_PERF=true` and start
+     the cluster by using the command `./vstart.sh -n -d -x --bluestore`. 
+   * Build with `vstart-base` using debug flags in cmake, compile, and deploy
+     via `./vstart.sh -d -n --bluestore`.
+   * To containerize, generate configurations with `vstart.sh`, and deploy with
+     Docker, mapping directories and configuring the network.
+   * Manage containers using `docker run`, `stop`, and `rm`. For detailed
+     setups, consult the Ceph-Container repository.
+
+##  Troubleshooting     
+ 
+   * Cluster Fails to Start: Look for errors in the logs under the `out/`
+     directory.
+   * OSD Crashes: Check the OSD logs for errors.
+   * Cluster in a `Health Error` State: Run the `ceph status` command to
+     identify the issue.
+   * RocksDB Errors: Look for RocksDB-related errors in the OSD logs.
 
 ## Building a source tarball