Make small improvements to the documentation

README.md

@@ -26,7 +26,7 @@ ScubaGear uses a three-step process:
 
 ## Getting Started
 
-To install ScubaGear from [PSGallery](https://www.powershellgallery.com/packages/ScubaGear), open a PowerShell 5 terminal and install the module:
+To install ScubaGear from [PSGallery](https://www.powershellgallery.com/packages/ScubaGear), open a PowerShell 5 terminal on a Windows computer and install the module:
 
 ```powershell
 # Install ScubaGear

docs/configuration/configuration.md

@@ -32,7 +32,7 @@ Invoke-SCuBA `
 
 ### Typical Use
 
-The [typical use](https://github.com/cisagov/ScubaGear/blob/main/PowerShell/ScubaGear/Sample-Config-Files/typical_config.yaml) example config file includes multiple products specified as a list and an M365 environment. Additional product values are commented out and will not be included, but are retained in the config file to easily add them back later. 
+The [typical use](https://github.com/cisagov/ScubaGear/blob/main/PowerShell/ScubaGear/Sample-Config-Files/typical_config.yaml) example config file includes multiple products specified as a list and an M365 environment. Additional product values are commented out and will not be included in the testing, but they are retained in the config file to easily add them back later.
 
 ScubaGear can be invoked with this config file:
 

docs/configuration/parameters.md

@@ -4,7 +4,7 @@ The `Invoke-SCuBA` cmdlet has several command-line parameters, which are describ
 
 > **Note**: Some parameters can also be specified in a [configuration file](configuration.md). If specified in both, command-line parameters have precedence over the config file. 
 
-> **Note**: Parameters use the Pascal case convention , and their names are consistent with those in the configuration file.
+> **Note**: Parameters use the Pascal case convention, and their names are consistent with those in the configuration file.
 
 ## AppID
 
@@ -68,7 +68,7 @@ Here's an example using `-ConfigFilePath`:
 ```powershell
 # Set the inputs using a configuration file
 Invoke-SCuBA -ProductNames teams `
-  -ConfigFilePath C:\users\<username>\Documents\scuba\config.json
+  -ConfigFilePath C:\users\johndoe\Documents\scuba\config.json
 ```
 
 If `-ConfigFilePath` is specified, default values will be used for any parameters that are not added to the config file. These default values are shown in the [full config file](https://github.com/cisagov/ScubaGear/blob/main/PowerShell/ScubaGear/Sample-Config-Files/full_config.yaml).  
@@ -89,7 +89,7 @@ More information about the configuration file can be found on the [configuration
 | Config File | No     |  
 
 ```powershell
-# View HTML report in dark mode
+# View the HTML report in dark mode
 Invoke-SCuBA -ProductNames teams `
   -DarkMode
 ```
@@ -106,7 +106,7 @@ Invoke-SCuBA -ProductNames teams `
 | Config File | Yes    |  
 
 ```powershell
-# Delete the auth token
+# Delete the auth tokens
 Invoke-SCuBA -ProductNames teams `
   -DisconnectOnExit
 ```
@@ -162,7 +162,7 @@ The list of acceptable values are:
 
 ## MergeJson
 
-**MergeJson** combines the JSON files (named `TeamsReport.json`) in the `IndividualReports` folder together with the `ProviderSettingsExport.json` into an uber JSON file. These  files are deleted, though the combined report, `TestResults.json` is not deleted.
+**MergeJson** combines the individual JSON files (named `TeamsReport.json`) in the `IndividualReports` folder together with the `ProviderSettingsExport.json` into an uber JSON file named `ScubaResults.json`. The individual JSON files are deleted.
 
 | Parameter   | Value  |
 |-------------|--------|
@@ -172,7 +172,7 @@ The list of acceptable values are:
 | Config File | No     |  
 
 ```powershell
-# Delete the JSON files
+# Create a merged JSON file
 Invoke-SCuBA -ProductNames teams `
   -MergeJson
 ```
@@ -185,13 +185,13 @@ Invoke-SCuBA -ProductNames teams `
 |-------------|----------------------------------------|
 | Optional    | Yes                                    |
 | Datatype    | String                                 |
-| Default     | `C:\Users\<username>\.scubagear\Tools` |
+| Default     | `C:\Users\johndoe\.scubagear\Tools` |
 | Config File | Yes                                    |
 
 ```powershell
 # Change the directory that contains the OPA exe
 Invoke-SCuBA -ProductNames teams `
-  -OPAPath "C:\Users\<username>\Downloads"
+  -OPAPath "C:\Users\johndoe\Downloads"
 ```
 
 > **Note**: Path can be absolute or relative.
@@ -231,7 +231,7 @@ Invoke-SCuBA -ProductNames teams `
 | Config File | Yes                       |  
 
 ```powershell
-# Put the results in the testing folder
+# Change the output folder
 Invoke-SCuBA -ProductNames teams `
   -OutFolderName testing
 ```
@@ -250,7 +250,7 @@ Invoke-SCuBA -ProductNames teams `
 > **Note**: This parameter does not work if the `-MergeJson` parameter is not present.
 
 ```powershell
-# Put the results in the testing folder
+# Change the output JSON file
 Invoke-SCuBA -ProductNames teams `
   -OutJsonFileName myresults `
   -MergeJson
@@ -268,7 +268,7 @@ Invoke-SCuBA -ProductNames teams `
 | Config File | Yes                                        |
 
 ```powershell
-# Put the results in the testing folder
+# Change the output path
 Invoke-SCuBA -ProductNames teams `
   -OutPath myresults
 ```
@@ -287,7 +287,7 @@ Invoke-SCuBA -ProductNames teams `
 | Config File | Yes                      |  
 
 ```powershell
-# Put the results in the testing folder
+# Change the provider settings file
 Invoke-SCuBA -ProductNames teams `
   -OutProviderFileName mysettings
 ```
@@ -306,7 +306,7 @@ Invoke-SCuBA -ProductNames teams `
 | Config File | Yes           |  
 
 ```powershell
-# Put the results in the testing folder
+# Change the rego file
 Invoke-SCuBA -ProductNames teams `
   -OutRegoFileName mytestresults
 ```
@@ -325,7 +325,7 @@ Invoke-SCuBA -ProductNames teams `
 | Config File | Yes               |  
 
 ```powershell
-# Put the results in the testing folder
+# Change the HTML report file
 Invoke-SCuBA -ProductNames teams `
   -OutReportName myreport
 ```
@@ -363,7 +363,7 @@ Invoke-SCuBA -ProductNames teams, exo
 
 ## Quiet
 
-**Quiet** prevents the HTML report will not be opened in an external web browser.
+**Quiet** prevents the HTML report from being opened in an external web browser.
 
 | Parameter   | Value  |
 |-------------|--------|

docs/execution/execution.md

@@ -1,6 +1,6 @@
 # ScubaGear Execution
 
-ScubaGear is executed with the `Invoke-SCuBA` command, and it can be invoked interactively or non-interactively. Both modes require the appropriate [permissions](../prerequisites/permissions.md) to be configured and the [dependencies](../prerequisites/dependencies.md) to be installed. Additionally, if ScubaGear was downloaded from GitHub, the module must be imported.
+ScubaGear is executed with the `Invoke-SCuBA` command on a Windows computer, and it can be invoked interactively or non-interactively. Both modes require the appropriate [permissions](../prerequisites/permissions.md) to be configured and the [dependencies](../prerequisites/dependencies.md) to be installed. Additionally, if ScubaGear was downloaded from GitHub, the module must be imported.
 
 ## Import Module
 
@@ -33,7 +33,7 @@ To assess one product, use the `-ProductNames` flag with a product name:
 Invoke-SCuBA -ProductNames teams
 ```
 
-The complete list of all product names can be found on the [parameters](../configuration/parameters.md#product-names) page.
+The complete list of all product names can be found on the [parameters](../configuration/parameters.md#productnames) page.
 
 ### Multiple Products
 
@@ -58,7 +58,7 @@ More information about the resulting reports can be found on the [reports](repor
 
 ## Non-interactive Mode
 
-Non-interactive mode means that the credentials that are required by the underlying Microsoft libraries are supplied via command-line parameters or the config file. It uses an Entra ID [service principal](../permissions/noninteractive.md) and a certificate thumbprint, thus enabling ScubaGear to be used in automated processes, such as pipelines and scheduled jobs. 
+Non-interactive mode means that the credentials that are required by the underlying Microsoft libraries are supplied via command-line parameters or the config file. It uses an Entra ID [service principal](../prerequisites/noninteractive.md) and a certificate thumbprint, thus enabling ScubaGear to be used in automated processes, such as pipelines and scheduled jobs. 
 
 ```powershell
 # Assess with service principal

docs/execution/reports.md

@@ -2,10 +2,12 @@
 
 When ScubaGear runs, it creates a new time-stamped subdirectory wherein it will write all of the results of its testing. What follows are the default names for the various outputs, which can be changed using the corresponding [parameters](../configuration/parameters.md).
 
-* `IndividualReports` - This directory contains the detailed reports for each product tested.
-* `BaselineReports.html` - This HTML file is a summary of the detailed reports. By default, this file is automatically opened in a web browser after running ScubaGear.
-* `ProvideSettingsExport.json`- This JSON file contains all of the information that ScubaGear extracted from the products.  A highly-motivated admin might find this useful for understanding how ScubaGear arrived at its results.
-* `TestResults.csv` - This CSV file contains the test results in a format can could be automatically parsed by a downstream system.
-* `TestResults.json` - This JSON file contains the test results in a format can could be automatically parsed by a downstream system.
+| Result                       | Purpose   |
+|------------------------------|-----------|
+| `IndividualReports`          | This directory contains the detailed reports for each product tested. |
+| `BaselineReports.html`       | This HTML file is a summary of the detailed reports. By default, this file is automatically opened in a web browser after running ScubaGear. |
+| `ProvideSettingsExport.json` | This JSON file contains all of the information that ScubaGear extracted from the products.  A highly-motivated admin might find this useful for understanding how ScubaGear arrived at its results. |
+| `TestResults.csv`            | This CSV file contains the test results in a format can could be automatically parsed by a downstream system. |
+| `TestResults.json`           | This JSON file contains the test results in a format can could be automatically parsed by a downstream system. |
 
 You can learn more about setting parameters on the [parameters](../configuration/parameters.md) page.

docs/installation/uninstall.md

@@ -20,7 +20,7 @@ Uninstall-Module -Name ScubaGear
 
 ```powershell
 # Delete .scubagear folder
-Remove-Item C:\Users\<username>\.scubagear
+Remove-Item C:\Users\johndoe\.scubagear
 ```
 
 * If ScubaGear was [downloaded from GitHub](github.md), delete the ScubaGear folder that was extracted from the zip file.

docs/prerequisites/dependencies.md

@@ -7,13 +7,15 @@ Before [executing](../execution/execution.md) ScubaGear, its dependencies must b
 Initialize-SCuBA 
 ```
 
+> **Note**: ScubaGear utilizes several libraries from Microsoft to read data about their product configurations.  At least one of these libraries is tied to PowerShell 5.  Until Microsoft updates their library, ScubaGear will continue to use PowerShell 5.  As this version is only available on Windows, ScubaGear will only run on Windows.
+
 `Initialize-SCuBA` will install several modules on your system. These modules are listed in [RequiredVersions.ps1](https://github.com/cisagov/ScubaGear/blob/main/PowerShell/ScubaGear/RequiredVersions.ps1).  It will also install [OPA](https://www.openpolicyagent.org).
 
 > **Note**: The `Initialize-SCuBA` cmdlet creates a `.scubagear` folder in the users home directory.  This is where it stores OPA and any other related files.
 
 ## OPA Installation
 
-Normally, the `Initialize-SCuBA` cmdlet installs OPA.  This can be verified by looking for the OPA executable file in `C:\Users\<username>\.scubagear\Tools`.  If it failed to do so, or you set a parameter to prevent it from doing so, you can install OPA separately.
+Normally, the `Initialize-SCuBA` cmdlet installs OPA.  This can be verified by looking for the OPA executable file in `C:\Users\johndoe\.scubagear\Tools`.  If it failed to do so, or you set a parameter to prevent it from doing so, you can install OPA separately.
 
 Try this cmdlet first:
 
@@ -38,7 +40,7 @@ If that fails, you can manually download the OPA executable.
 
 * On the main portion of the screen, find the paragraph in the blue box that begins with "Windows users can obtain the OPA executable from here" and click the link in "here" to download the executable.
 
-* Locate the downloaded executable file and move it to `C:\Users\<username>\.scubagear\Tools`, creating the `Tools` folder if it does not already exist.
+* Locate the downloaded executable file and move it to `C:\Users\johndoe\.scubagear\Tools`, creating the `Tools` folder if it does not already exist.
 
 To verify that OPA is working, use the following command to check the version:
 

docs/troubleshooting/graph.md

@@ -19,7 +19,7 @@ This error can be seen when running ScubaGear. It is due to a [bug](https://gith
 
 ```powershell
 # Delete folder with Graph tokens and configuration info.
-rm -r C:\Users\<username>\.graph
+rm -r C:\Users\johndoe\.graph
 ```
 
 After deleting the `.graph` folder in your home directory, re-run ScubaGear, and the error should disappear.