Rework documentation for new upgrading section

README.md

@@ -56,9 +56,10 @@ The majority of the conformance checks done by ScubaGoggles rely on [GWS Admin l
 - [Reviewing Output](/docs/usage/ReviewOutput.md)
 - [Limitations](/docs/usage/Limitations.md)
 
-### Upgrading and Maintenance 
-- [Upgrading ScubaGoggles](/docs/troubleshooting/Upgrading.md#upgrading-scubagoggles)
-- [Upgrading OPA](/docs/troubleshooting/Upgrading.md#upgrading-opa)
+### Upgrading and Maintenance
+- [Upgrading ScubaGoggles](/docs/upgrading/Upgrading.md#upgrading-scubagoggles)
+- [Upgrading OPA](/docs/upgrading/Upgrading.md#upgrading-opa)
+
 ### Troubleshooting
 - [Lots of Manual Checks](/docs/troubleshooting/Troubleshooting.md#lots-of-manual-checks)
 - [Not Authorized to Access This Resource](/docs/troubleshooting/Troubleshooting.md#not-authorized-to-access-this-resource)

docs/installation/DownloadAndInstall.md

@@ -1,6 +1,6 @@
 # Download and Python Install
 > [!NOTE]
-> Previously installed a different version of ScubaGoggles? See [Troubleshooting: Upgrading ScubaGoggles](/docs/troubleshooting/Troubleshooting.md#upgrading-scubagoggles).
+> Previously installed a different version of ScubaGoggles? See [Upgrading ScubaGoggles](/docs/upgrading/Upgrading.md#upgrading-scubagoggles).
 
 ## Downloading the Latest Release
 To download ScubaGoggles:

docs/troubleshooting/Troubleshooting.md

@@ -1,18 +1,5 @@
 # Troubleshooting
 
-## Upgrading ScubaGoggles
-Assuming you installed ScubaGoggles as described in [Download and Install](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/DownloadAndInstall.md), upgrading to the lastest version of ScubaGoggles should be as simple as:
-- Repeating the steps described in [Download and Install](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/DownloadAndInstall.md) with the new release.
-- Making the OPA executable available, by either:
-    - downloading the executable again as described in [Download the OPA executable](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/OPA.md),
-    - copying the executable from the old release folder to the new release folder, or
-    - using the `--opapath` parameter to tell ScubaGoggles where to look for the executable.
-- Making your credentials available, by either:
-    - copying your `credentials.json` file to the new release folder or
-    - using the `--credentials` parameter to tell ScubaGoggles where to look for your credentials.
-
-If instead you cloned the ScubaGoggles repo and wish to run ScubaGoggles on the latest code from main (only recommended for development purposes), be sure to run `python -m pip install .` inside the ScubaGoggles directory after pulling the latest code.
-
 ## Lots of Manual Checks
 The report output by ScubaGoggles may indicate that many manual checks are needed (e.g., https://github.com/cisagov/ScubaGoggles/issues/260). This is a symptom of ScubaGoggles' primary limitation. As the API calls to check most of the settings relevant to ScubaGoggles are have not been made public by Google, ScubaGoggles relies on [GWS Admin log events](https://support.google.com/a/answer/4579579?hl=en) to determine the current state. If there are no log events corresponding to a SCuBA baseline policy (e.g., because the setting hasn't been changed within the past 6 months), ScubaGoggles will indicate that the setting needs to be checked manually. See [Limitations](/docs/usage/Limitations.md) for more details.
 

docs/upgrading/Upgrading.md

@@ -0,0 +1,22 @@
+# Upgrading and Maintenance
+
+## Upgrading ScubaGoggles
+Assuming you installed ScubaGoggles as described in [Download and Install](/docs/installation/DownloadAndInstall.md), upgrading to the lastest version of ScubaGoggles should be as simple as:
+- Repeating the steps described in [Download and Install](/docs/installation/DownloadAndInstall.md) with the new release.
+- Making the OPA executable available, by either:
+    - downloading the executable again as described in [Download the OPA executable](/docs/installation/OPA.md),
+    - copying the executable from the old release folder to the new release folder, or
+    - using the `--opapath` parameter to tell ScubaGoggles where to look for the executable.
+- Making your credentials available, by either:
+    - copying your `credentials.json` file to the new release folder or
+    - using the `--credentials` parameter to tell ScubaGoggles where to look for your credentials.
+
+If instead you cloned the ScubaGoggles repo and wish to run ScubaGoggles on the latest code from main (only recommended for development purposes), be sure to run `python -m pip install .` inside the ScubaGoggles directory after pulling the latest code.
+
+## Upgrading OPA
+While new versions of OPA are periodically released, it is only necessary to upgrade OPA if the version you have locally is unsupported. Running `python download_opa.py --help` lists the supported OPA versions.
+
+Upgrading OPA is as simple as downloading the desired executable, which can be done by running the `download_opa.py` script again. See [Download the OPA executable](/docs/installation/OPA.md) for detailed instructions.
+
+## Navigation
+- Return to [Documentation Home](/README.md)