STP-3680: Minor edits to improve documentation

docs/about_sat/command_authentication.md

@@ -37,7 +37,7 @@ describing SAT commands and the types of authentication they require.
 |`sat xname2nid`|Requires authentication to the API gateway.|`sat-xname2nid`|Translate node and node BMC XNames to node IDs.|
 |`sat switch`|**This command has been deprecated.** It has been replaced by `sat swap`.|
 
-In order to authenticate to the API gateway, you must run the `sat auth`
+In order to authenticate to the API gateway, run the `sat auth`
 command. This command will prompt for a password on the command line. The
 username value is obtained from the following locations, in order of higher
 precedence to lower precedence:

docs/about_sat/sat_in_csm.md

@@ -21,7 +21,7 @@ If the SAT product stream is not installed, there will be no configuration conte
 configurations that apply to management NCNs (for example, `management-23.5.0`) should not include a SAT layer.
 
 The SAT configuration layer modifies the permissions of files left over from prior installations of SAT, so that the
-Keycloak username that authenticates to the API gateway cannot be read by users other than `root`. Specifically, it
+Keycloak username that authenticates to the API gateway cannot be read by users other than `root`. Specifically,
 it does the following:
 
 - Modifies the `sat.toml` configuration file which contains the username so that it is only readable by `root`.

docs/about_sat/view_sat_docs.md

@@ -1,14 +1,14 @@
 # View SAT Documentation
 
-You can view the System Admin Toolkit (SAT) documentation both online and
-offline as described in this section.
+View the System Admin Toolkit (SAT) documentation both online and
+offline by using the information in this section.
 
 ## Online Documentation
 
 The SAT documentation can be found online in HTML form at the following link:
 [SAT Documentation](https://cray-hpe.github.io/docs-sat). The navigation pane
-on the left of the HTML page is ordered alphabetically. You can also navigate
-an individual topic's headings by using the **Headings** icon at the top of the
+on the left of the HTML page orders topics alphabetically. Navigate an
+individual topic's headings by using the **Headings** icon at the top of the
 page, as shown in the following images.
 
 ![HTML Heading Icon](../img/HTML_Heading_Icon.png)
@@ -17,8 +17,8 @@ page, as shown in the following images.
 
 The documentation can also be viewed online in GitHub by navigating to the
 `docs/` subdirectory of the
-[`docs-sat` repository](https://github.com/Cray-HPE/docs-sat/tree/integration).
-There you can navigate an individual topic's headings with a similar
+[`docs-sat` repository](https://github.com/Cray-HPE/docs-sat/tree/main).
+Navigate an individual topic's headings with a similar
 **Headings** icon at the top of the page, as shown in the following images.
 
 ![GitHub Heading Icon](../img/GitHub_Heading_Icon.png)

docs/dashboards/SAT_Kibana_Dashboards.md

@@ -49,7 +49,7 @@ table.
 
 By default, search highlighting is enabled. This procedure instructs how to disable search highlighting.
 
-The Kibana Dashboard should be open on your system.
+The Kibana Dashboard should be open on the system.
 
 1. Navigate to **Management**
 

docs/external_system.md

@@ -14,7 +14,7 @@ following:
 - The local host information displayed by the `--local` option of `sat showrev`
 
 Installing SAT on an external system is not an officially supported configuration.
-These instructions are provided "as-is" with the hope that they can useful for
+These instructions are provided "as-is" with the hope that they can be useful for
 users who desire additional flexibility.
 
 Certain additional steps may need to be taken to install and configure SAT
@@ -60,7 +60,7 @@ use externally-accessible API endpoints exposed by CSM.
    SAT CSM Python dependency packages are not currently distributed publicly as
    source packages or binary distributions. They must be installed from
    their source code hosted on GitHub. Also, to install the `cray-product-catalog`
-   Python package, you must first clone it locally. Use the following steps to
+   Python package, first clone it locally. Use the following steps to
    modify the SAT CSM Python dependencies so they can be installed from their source
    code.
 
@@ -112,9 +112,9 @@ use externally-accessible API endpoints exposed by CSM.
       csm-api-client@git+https://github.com/Cray-HPE/python-csm-api-client@release/1.1
       ```
 
-      **Note:** For versions newer than 3.19, you will see both `cray-product-catalog`
-      and `csm-api-client`. For version 3.19 and older, you will only see
-      `cray-product-catalog`.
+      **Note:** For versions newer than 3.19, the output will show both
+      `cray-product-catalog` and `csm-api-client`. For version 3.19 and older,
+      the output will only show `cray-product-catalog`.
 
 1. (`(venv) user@hostname>`) Install the modified SAT dependencies.
 
@@ -301,7 +301,7 @@ use externally-accessible API endpoints exposed by CSM.
    username = "user"
    ```
 
-1. (`user@hostname>`) Run `sat auth`, and enter your password when prompted.
+1. (`user@hostname>`) Run `sat auth`, and enter the password when prompted.
 
    The admin account used to authenticate with `sat auth` must be enabled in
    Keycloak and must have its *assigned role* set to *admin*.

docs/install.md

@@ -67,7 +67,7 @@ managed images.
 
 ## Post-Installation Procedures
 
-After installing SAT with IUF, you must complete the following SAT configuration
+After installing SAT with IUF, complete the following SAT configuration
 procedures before using SAT:
 
 - [Authenticate SAT Commands](#authenticate-sat-commands)
@@ -84,7 +84,7 @@ procedures before using SAT:
 
 ### Authenticate SAT Commands
 
-To run SAT commands on the manager NCNs, you must first set up authentication
+To run SAT commands on the manager NCNs, first set up authentication
 to the API gateway. For more information on authentication types and
 authentication credentials, see [SAT Command
 Authentication](about_sat/command_authentication.md).
@@ -106,7 +106,7 @@ the [*Cray System Management Documentation*](https://cray-hpe.github.io/docs-csm
 The following is the procedure to globally configure the username used by SAT and
 authenticate to the API gateway.
 
-1. (`ncn-m001#`) Generate a default SAT configuration file, if one does not exist.
+1. (`ncn-m001#`) Generate a default SAT configuration file if one does not exist.
 
    ```bash
    sat init
@@ -133,7 +133,7 @@ authenticate to the API gateway.
    username = "crayadmin"
    ```
 
-1. (`ncn-m001#`) Run `sat auth`. Enter your password when prompted.
+1. (`ncn-m001#`) Run `sat auth`. Enter the password when prompted.
 
    ```bash
    sat auth
@@ -250,9 +250,8 @@ Information](#set-system-revision-information)).
 
 ### (Optional) Configure Multi-tenancy
 
-If SAT is being installed on a multi-tenant system, you can configure the tenant
-name at this point. For more information, see [Configure
-multi-tenancy](usage/multi-tenancy.md).
+If installing SAT on a multi-tenant system, the tenant name can be configured
+at this point. For more information, see [Configure multi-tenancy](usage/multi-tenancy.md).
 
 ### Set System Revision Information
 

docs/release_notes/sat_2.2_release_notes.md

@@ -36,7 +36,7 @@ export PATH=/sat/venv/bin:$PATH
 sat status
 ```
 
-(`(CONTAINER_ID) sat-container#`) You can also source the file `/sat/venv/bin/activate`:
+(`(CONTAINER_ID) sat-container#`) Another option is to source the file `/sat/venv/bin/activate`:
 
 ```bash
 source /sat/venv/bin/activate
@@ -123,8 +123,8 @@ For more information, see
 
 ## Improvements to `sat status`
 
-A `Subrole` column has been added to the output of `sat status`. This allows you
-to easily differentiate between master, worker, and storage nodes in the
+A `Subrole` column has been added to the output of `sat status`. This allows
+easy differentiation between master, worker, and storage nodes in the
 management role, for example.
 
 Hostname information from SLS has been added to `sat status` output.

docs/release_notes/sat_2.4_release_notes.md

@@ -86,7 +86,7 @@ new features:
   key is deprecated.
 - To specify an image that depends on another image in the input file, the
   dependent image should specify the dependency under `base.image_ref`.
-  You should no longer use the IMS name of the image on which it depends.
+  Going forward, do not use the IMS name of the image on which it depends.
 - The image used by a session template should now be specified under
   `image.ims.name`, `image.ims.id`, or `image.image_ref`. Specifying a string
   value directly under the `image` key is deprecated.
@@ -116,8 +116,8 @@ that interact with BOS:
 - `sat bootsys`
 - `sat status`
 
-By default, SAT uses BOS `v1`. However, you can choose the BOS version you want
-to use. For more information, see [Change the BOS Version](../usage/change_bos_version.md).
+By default, SAT uses BOS `v1`. To change the default to a different BOS version,
+see [Change the BOS Version](../usage/change_bos_version.md).
 
 ## Added BOS Fields to `sat status`
 

docs/release_notes/sat_2.5_release_notes.md

@@ -9,7 +9,7 @@ The 2.5.17 version of the SAT product includes:
 
 ## New `sat` Commands
 
-`sat jobstat` allows you to access application and job data through the command
+`sat jobstat` allows access to application and job data through the command
 line. It provides a table summarizing information for all jobs on the system.
 
 ## Changes to `sat bootprep`
@@ -39,8 +39,8 @@ line. It provides a table summarizing information for all jobs on the system.
   For more information, see
   [Hyphens in HPC CSM Software Recipe Variables](../usage/sat_bootprep.md#hyphens-in-hpc-csm-software-recipe-variables).
 
-- In `sat bootprep` input files, you can now render the value of the `playbook`
-  property of CFS configuration layers with Jinja2 templates.
+- In `sat bootprep` input files, the value of the `playbook` property of CFS
+  configuration layers can now be rendered with Jinja2 templates.
 
   For more information, see
   [Values Supporting Jinja2 Template Rendering](../usage/sat_bootprep.md#values-supporting-jinja2-template-rendering).
@@ -102,8 +102,8 @@ This change to BOS `v2` impacts the following commands that interact with BOS:
 - `sat bootsys`
 - `sat status`
 
-If needed, you can choose the BOS version you want to use. For more information,
-see [Change the BOS Version](../usage/change_bos_version.md).
+To change the default to a different BOS version, see
+[Change the BOS Version](../usage/change_bos_version.md).
 
 ## Security
 

docs/release_notes/sat_2.6_release_notes.md

@@ -41,19 +41,19 @@ No new `sat` commands were added in SAT 2.6.
   wildcards similar to how prefix filters were used in older versions of SAT.
   For more information, see [Define IMS Images](../usage/sat_bootprep.md#define-ims-images).
 
-- Support for multiple architectures was added to `sat bootprep`. You can
-  filter base IMS images and recipes from products based on their target
-  architecture. You can also specify target architectures in boot sets of BOS
-  session templates. For more information, see
+- Support for multiple architectures was added to `sat bootprep`. It is now
+  possible to filter base IMS images and recipes from products based on their
+  target architecture. This support also allows specifying target architectures
+  in boot sets of BOS session templates. For more information, see
   [Filter Base Images or Recipes from a Product](../usage/sat_bootprep.md#filter-base-images-or-recipes-from-a-product)
   and
   [Define BOS Session Templates](../usage/sat_bootprep.md#define-bos-session-templates).
 
-- You can combine multiple image or recipe filters when specifying a base
-  image or recipe from a product. If you specify multiple filters, the unique
-  base image or recipe that satisfies all of the given filters is selected. An
-  error occurs if either no images or recipes match the given filters or if
-  more than one image or recipe matches the given filters.
+- When specifying a base image or recipe from a product, `sat bootprep`
+  can combine multiple image or recipe filters. When specifying multiple
+  filters, the unique base image or recipe that satisfies all of the given
+  filters is selected. An error occurs if either no images or recipes match the
+  given filters or if more than one image or recipe matches the given filters.
 
 - In CFS configuration layers, support was added for the new `imsRequireDkms`
   field under the `specialParameters` section. CFS configurations in bootprep
@@ -62,8 +62,8 @@ No new `sat` commands were added in SAT 2.6.
 
 ## Other SAT Changes
 
-- You can add a new `s3.cert_verify` option to the SAT configuration file that
-  controls whether certificate verification is performed when accessing S3.
+- Add the new `s3.cert_verify` option to the SAT configuration file to
+  control whether certificate verification is performed when accessing S3.
 
 - Log messages spanning multiple lines now print the log level on each line
   instead of only at the beginning of the message.

docs/uninstall_and_downgrade.md

@@ -101,7 +101,7 @@ ability to switch between SAT versions will be removed in a future release.
    - Ensure that the SAT CFS configuration content exists as a layer in all CFS configurations that are
      associated with NCNs with the role "Management" and subrole "Master" (for example, the CFS configuration
      `management-23.5.0`). Specifically, it will ensure that the layer refers to the version of SAT CFS
-     configuration content associated with the version of SAT to which you are switching.
+     configuration content associated with the version of SAT to which the system is switching.
 
    ```bash
    prodmgr activate sat 2.5.15
@@ -213,11 +213,11 @@ ability to switch between SAT versions will be removed in a future release.
    sat 3.7.0
    ```
 
-   **Note:** Upon first running `sat`, you may see additional output while the `sat`
-   container image is downloaded. This will occur the first time `sat` is run on
-   each manager NCN. For example, if you run `sat` for the first time on `ncn-m001`
-   and then for the first time on `ncn-m002`, you will see this additional output
-   both times.
+   **Note:** Upon first running `sat`, there might be additional output while
+   the `sat` container image is downloaded. This occurs the first time `sat`
+   is run on each manager NCN. For example, when running `sat` for the first time
+   on `ncn-m001` and then for the first time on `ncn-m002`, this additional
+   output is seen both times.
 
    ```text
    Trying to pull registry.local/cray/cray-sat:3.7.0-20210514024359_9fed037...

docs/upgrade.md

@@ -67,7 +67,7 @@ managed images.
 
 ## Post-Upgrade Procedures
 
-After upgrading SAT with IUF, it is recommended that you complete the following
+After upgrading SAT with IUF, it is recommended to complete the following
 procedures before using SAT:
 
 - [Remove Obsolete Configuration File Sections](#remove-obsolete-configuration-file-sections)

docs/usage/change_bos_version.md

@@ -1,13 +1,13 @@
 # Change the BOS Version
 
-By default, SAT uses Boot Orchestration Service (BOS) version two (`v2`). You can
-select the BOS version to use for individual commands with the `--bos-version`
+By default, SAT uses Boot Orchestration Service (BOS) version two (`v2`).
+Select the BOS version to use for individual commands with the `--bos-version`
 option. For more information on this option, refer to the man page for a specific
 command.
 
-You can also configure the BOS version to use in the SAT configuration file. Do
-this under the `api_version` setting in the `bos` section of the configuration
-file. If the system is using an existing SAT configuration file from an older
+Another way to change the BOS version is by configuring it under the
+`api_version` setting in the `bos` section of the SAT configuration file.
+If the system is using an existing SAT configuration file from an older
 version of SAT, the `bos` section might not exist. In that case, add the `bos`
 section with the BOS version desired in the `api_version` setting.
 

docs/usage/multi-tenancy.md

@@ -3,12 +3,12 @@
 SAT supports supplying tenant information to CSM services in order to allow
 tenant admins to use SAT within their tenant. By default, the tenant name is
 not set, and SAT will not send any tenant information with its requests to
-CSM services. You can configure the tenant name either in the SAT configuration
-file or on the command line.
+CSM services. Configure the tenant name either in the SAT configuration file
+or on the command line.
 
 ## Configure the Tenant Name in the SAT Configuration File
 
-You can set the tenant name in the SAT configuration file using the
+Set the tenant name in the SAT configuration file using the
 `api_gateway.tenant_name` option.
 
 Here is an example:
@@ -20,7 +20,7 @@ tenant_name = "my_tenant"
 
 ## Configure the Tenant Name on the Command Line
 
-You can set the tenant name for each `sat` invocation using the `--tenant-name`
+Set the tenant name for each `sat` invocation using the `--tenant-name`
 option. The `--tenant-name` option must be specified before the subcommand
 name.
 

docs/usage/sat_and_iuf.md

@@ -29,12 +29,12 @@ the [*Cray System Management Documentation*](https://cray-hpe.github.io/docs-csm
 
 ### SAT Variable Limitations
 
-When using `sat bootprep` outside of IUF, you might encounter problems
-substituting variables into the default bootprep input files. Complex variables
-like `"{{ working_branch }}"` cannot be completely resolved outside of IUF and
+When using `sat bootprep` outside of IUF, substituting variables into the
+default bootprep input files might cause problems. Complex variables like
+`"{{ working_branch }}"` cannot be completely resolved outside of IUF and
 its internal session variables. Thus, the default `product_vars.yaml` file is
 unusable with only the `sat bootprep` command when variables like
-`"{{ working_branch }}"` are used. To work around this limitation if you are
+`"{{ working_branch }}"` are used. To work around this limitation when
 substituting complex variables, use the internal IUF `session_vars.yaml` file
 with `sat bootprep` and the default bootprep input files.
 
@@ -57,7 +57,7 @@ with `sat bootprep` and the default bootprep input files.
 The `sat bootprep run` command uses information from the bootprep input files
 to create CFS configurations, IMS images, and BOS session templates. To restrict
 this creation into separate stages, use the `--limit` option and list whether
-you want to create `configurations`, `images`, `session_templates`, or some
+to create `configurations`, `images`, `session_templates`, or some
 combination of these. IUF uses the `--limit` option in this way to install,
 upgrade, and deploy products on a system in stages.