Chore: upgrade docs Trey edits (#5005)

Co-authored-by: David Dai <ddai@tobikodata.com>

Author: treysp

docs/cloud/features/upgrade/upgrade-ui-available.png

@@ -1,59 +1,75 @@
-# Upgrades
+# Upgrading Tobiko Cloud
 
-Upgrading a Tobiko Cloud project can be done by going to `Settings > Upgrade`.
-If a new version is available for your project, you'll see an upgrade page like the one below.
-You can choose to upgrade to the latest version or specify a custom version.
-Clicking the **Upgrade Now** button and confirming will start the upgrade process.
+Tobiko regularly releases new versions of Tobiko Cloud that add features and improve reliability.
 
-![Tobiko Cloud Upgrade Page](./upgrade/upgrade-ui-latest.png)
+This page describes how to upgrade your Tobiko Cloud projects to a newer version.
+
+## Upgrade availability
+
+Navigate to `Settings > Upgrade` in the Tobiko Cloud UI to determine whether a new version of Tobiko Cloud is available for your project.
+
+If your project is already up to date, you will see a grey message:
+
+![Tobiko Cloud Upgrade Already Up-to-Date](./upgrade/upgrade-ui-up-to-date.png)
+
+If a new version is available for your project, the page will include a notification box, version, and blue Upgrade Now button:
+
+![Tobiko Cloud Upgrade Page](./upgrade/upgrade-ui-available.png)
+
+## Upgrading a project
+
+On the Upgrade page, you can choose to upgrade to the latest version or specify a custom version.
 
 !!! info "Upgrade Permissions"
-    Only users with `Admin` permissions can perform upgrades.
+    Only users with Tobiko Cloud `Admin` permissions can perform upgrades.
+
+!!! danger "Upgrade Side Effects"
+    The upgrade process may take a few minutes to complete. During this time, your Tobiko Cloud project will be unavailable.
 
-!!! warning "Upgrade Preparations"
-    The upgrade process can take anywhere from a few minutes to over 30 minutes.
-    The total time depends on the size of your project and the complexity of the upgrade.
-    During this time, your Tobiko Cloud project will be unavailable. Any in-progress plans and runs will be aborted:
+    Any in-progress plans and runs will be aborted:
 
-    - Aborted plans will be stopped and must be recreated.
-    - Aborted runs will be automatically resumed shortly after the upgrade completes.
+      - Aborted plans will be stopped, and you must **manually** start them again.
+      - Aborted runs will be automatically resumed shortly after the upgrade completes.
 
     To avoid unexpected interruptions, please notify your team before starting the upgrade.
 
-## Custom Version
+### Latest Version
 
-Although it is recommended to always upgrade your Tobiko Cloud project to the latest version,
-there may be cases where a team needs to upgrade to a specific version.
+Click the **Upgrade Now** button and confirm to begin upgrading your project to the latest version.
 
-For example, a team might have separate staging and production projects.
-They may upgrade the staging project first, run tests, and only upgrade the production project after verifying that staging works as expected.
-If a new version is released during this testing period, the team may want to upgrade production to the same version used in staging.
-Custom version selection supports this workflow.
+![Tobiko Cloud Upgrade Page](./upgrade/upgrade-ui-latest.png)
 
-To specify a custom version, select the **Custom** tab on the Upgrade page and enter the desired version in the text box.
+### Custom Version
+
+We recommend upgrading your Tobiko Cloud project to the latest version, but you may prefer to upgrade to a specific version.
+
+For example, consider a team that has separate staging and production Tobiko Cloud projects. They upgrade the staging project first, run tests, and only upgrade the production project after verifying that staging works as expected.
+
+If a new version of Tobiko Cloud is released during this testing period, the latest available version will not match the version tested in staging. The team can specify a custom Tobiko Cloud version to upgrade production to the specific version that was already tested in staging.
+
+To specify a custom version, select the **Custom** tab on the Upgrade page and enter your desired version in the text box.
 
 ![Tobiko Cloud Upgrade Custom Version](./upgrade/upgrade-ui-custom-version.png)
 
-!!! info "Valid Custom Version"
-    Enter the custom version **without** the leading `v`.
-    The version must be valid and greater than the current version of the project.
-    If the custom version is not valid, an error message will be displayed.
+Make sure you are entering a valid custom version by:
 
-## Upgrade Progress
+  - Entering the custom version **without** the leading `v`
+  - Confirming that the version is valid and later than the current version of the project
 
-After starting the upgrade, a progress page will be shown.
-Once the upgrade is complete, you’ll be automatically redirected back to the upgraded Tobiko Cloud project.
+If your custom version is not valid, Tobiko Cloud will display an error message.
 
-![Tobiko Cloud Upgrade Progress](./upgrade/upgrade-ui-progress.png)
+After entering the custom version, click the **Upgrade Now** button and confirm to begin the upgrade process.
 
-## Project Already Up-to-Date
+## Upgrade Progress
 
-If the project is already on the latest version, you’ll see a message like the one below.
+Tobiko Cloud will display a progress page while the upgrade is in progress:
 
-![Tobiko Cloud Upgrade Already Up-to-Date](./upgrade/upgrade-ui-up-to-date.png)
+![Tobiko Cloud Upgrade Progress](./upgrade/upgrade-ui-progress.png)
+
+Once the upgrade is complete, Tobiko Cloud will automatically redirect you back to your upgraded project.
 
 ## Upgrade Support
 
-If you encounter an issue during the upgrade process, please [report an incident](./incident_reporting.md).
-Our support team will follow up as soon as possible.
-For the quickest response, we recommend upgrading Monday through Friday between 9 AM and 5 PM PST.
+If you encounter an issue during the upgrade process, please [report an incident](./incident_reporting.md). Our support team will follow up as soon as possible.
+
+For the quickest response, we recommend upgrading Monday through Friday between 9am and 5pm PST.

docs/cloud/features/upgrade/upgrade-ui-latest.png

@@ -111,8 +111,11 @@ nav:
     - "Getting Started": cloud/tcloud_getting_started.md
     - Cloud Features:
       - "Alerts & Notifications": cloud/features/alerts_notifications.md
-      - cloud/features/debugger_view.md
       - cloud/features/data_catalog.md
+      - cloud/features/debugger_view.md
+      - Maintenance:
+        - cloud/features/incident_reporting.md
+        - cloud/features/upgrades.md
       - Scheduler:
         - "Cloud": cloud/features/scheduler/scheduler.md
         - "Cloud Hybrid Deployments":
@@ -124,9 +127,8 @@ nav:
       - Security:
         - cloud/features/security/security.md
         - cloud/features/security/single_sign_on.md
-      - cloud/features/incident_reporting.md
-      - cloud/features/xdb_diffing.md
-      - cloud/features/upgrades.md
+      - Tools:
+        - cloud/features/xdb_diffing.md
 #      - Observability:
 #        - cloud/features/observability/overview.md
 #        - cloud/features/observability/model_freshness.md