Fix grammatical/clarity issues from review

Author: ashao

doc/contributing.rst

@@ -1,3 +1,4 @@
+.. _contributing:
 
 ******************
 Contributing Guide

doc/installation_instructions/basic.rst

@@ -4,9 +4,9 @@
 Basic Installation
 ******************
 
-The following instructions serve as a guide for installing both SmartSim and
-SmartRedis. SmartSim, despite being a Python-library, has a second build
-step for Redis and RedisAI. Please follow these instructions carefully.
+The following instructions guide you through installing SmartSim and SmartRedis.
+SmartSim, despite being a Python-library, has a second build step for Redis and
+RedisAI. Please follow these instructions carefully.
 
 .. note::
 
@@ -32,26 +32,29 @@ The base prerequisites to install SmartSim and SmartRedis wtih CPU-only support
 
 .. note::
 
-  GCC is recommended to build the backends for SmartSim. CUDA 11.8 requires GCC
-  9 or 11, CUDA 12 requires GCC 11 or higher. SmartRedis can be compiled with
-  GCC, Intel, Cray, and Nvidia compilers.
+  We suggest using GCC to build Redis, RedisAI, and the ML backends. For specific
+  version requirements see the :ref:`Requirements <requirements>` section.
+
+  SmartRedis can be compiled with GCC, Intel, Cray, and Nvidia compilers.
 
 ML Library Support
 ==================
 
-We currently support both Nvidia and AMD GPUs when using RedisAI for GPU
-inference. The support for these GPUs often depends on the version of the CUDA
-or ROCm stack that is availble on your machine. In _most_ cases, the versions of
-the ML frameworks are backwards compatible. If you encounter problems, please
-contact us and we can build the backend libraries for your desired version of
-CUDA and ROCm.
+SmartSim supports using Nvidia and AMD GPUs when using RedisAI for GPU
+inference. GPU support often depends on the version of the CUDA or ROCm stack
+that is available on your machine. In _most_ cases, the versions of the ML
+frameworks are backwards compatible. If you encounter problems, please contact
+us at (smartsim at hpe dot com) and we can build the backend libraries for your
+desired version of CUDA and/or ROCm.
 
 CPU backends are provided for Apple (both Intel and Apple Silicon) and Linux (x86_64).
 
 Be sure to reference the table below to find which versions of the ML libraries
 are supported for your particular platform. Additionally, see :ref:`Platform
 Installation Guide <platform-installation>` for helpful information regarding
-for specific systems.
+specific systems.
+
+.. _requirements:
 
 Linux
 -----
@@ -62,7 +65,7 @@ Linux
 
       Additional requirements:
 
-      * GCC <= 11
+      * GCC <= 11 (except 10)
       * CUDA Toolkit 11.7 or 11.8
       * cuDNN 8.9
 
@@ -84,6 +87,7 @@ Linux
 
       Additional requirements:
 
+      * GCC >= 11
       * CUDA Toolkit 12
       * cuDNN 8.9
 

doc/installation_instructions/platform.rst

@@ -3,12 +3,13 @@
 Platform Install Guide
 ======================
 
-HPC platforms have specific modules that users can often use so they do not
-need to retrieve all of the build dependencies themselves. Some machines
-have specific environment variables and/or configuration settings that need
-to be set for optimal performance. The below machines have vetted
-instructions, please feel free to contribute instructions for your own
-machine.
+
+HPC platforms often provide modules that enable user to avoid retrieving all
+build dependencies themselves. Additionally, some machines require environment
+variables and/or configuration settings that need to be set for optimal
+performance. The below machines have vetted instructions. Please feel free to
+contribute instructions for your own platform (see :ref:`Contributing Guide
+<contributing>`).
 
 .. include:: platform/frontier.rst
 .. include:: platform/perlmutter.rst

doc/installation_instructions/troubleshooting/cuda-dependencies.rst

@@ -10,22 +10,22 @@ and install these dependencies and configure your build environment.
 
 .. note::
 
-    At runtime, the environment in which the Orchestrator is launched must have
-    the cuDNN and CUDA Toolkit libraries findable by the link loader (e.g.
-    available in the ``LD_LIBRARY_PATH`` environment variable).
+    The Orchestrator must launched in an environment with the cuDNN and CUDA
+    Toolkit libraries findable by the link loader (e.g.  available in the
+    ``LD_LIBRARY_PATH`` environment variable).
 
 Download and install
 ^^^^^^^^^^^^^^^^^^^^
 
 **Step 1:** Find a location which is globally accessible and has sufficient
-storage space (about 12GB) and set an environment variable
+storage space (about 12GB) and set an environment variable:
 
 .. code-block:: bash
 
     export CUDA_TOOLKIT_INSTALL_PATH=/path/to/install/location/cudatoolkit
     export CUDNN_INSTALL_PATH=/path/to/install/location/cudnn
 
-**Step 2:** Download cudatoolkit and install it
+**Step 2:** Download cudatoolkit and install it:
 
 .. tabs::
 
@@ -43,12 +43,12 @@ storage space (about 12GB) and set an environment variable
             wget https://developer.download.nvidia.com/compute/cuda/12.5.0/local_installers/cuda_12.5.0_555.42.02_linux.run
             sh ./cuda_12.5.0_555.42.02_linux.run --toolkit --silent --toolkitpath=$CUDA_TOOLKIT_INSTALL_PATH
 
-**Step 3:** Download cuDNN
+**Step 3:** Download cuDNN:
 For cuDNN, follow `Nvidia's instructions
 <https://docs.nvidia.com/deeplearning/cudnn/installation/overview.html>`_ for
 downloading cuDNN version 8.9 for either CUDA-11 or CUDA-12.
 
-**Step 4:** Untar the cuDNN archive
+**Step 4:** Untar the cuDNN archive:
 
 .. tabs::
 
@@ -87,8 +87,8 @@ Option 2: Setup Modulefiles
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Alternatively, these environment variables can be setup by using environment
-modules instead. This can be especially useful when the CUDA dependencies are
-intended to be shared across users.
+modules. This is useful when the CUDA dependencies are intended to be shared
+across users.
 
 **Step 1:** Download these two modulefiles to a directory of your choosing
 

doc/installation_instructions/troubleshooting/custom_backends.rst

@@ -3,14 +3,15 @@ Custom ML backends
 
 The ML backends (Torch, ONNX Runtime, and Tensorflow) and their associated
 python packages have different versions and indices that can be supported based
-on the intended device (CPU, ROCM, CUDA-11, or CUDA-12). The officially
+on the intended device (CPU, ROCm, CUDA-11, or CUDA-12). The officially
 supported backends are stored in JSON files within the
 ``smartsim/_core/_install/configs/mlpackages`` directory.
 
-If you need to define a different version of the backend and/or the packages, we
-recommend that you copy one of the JSON files (for example the one at the end of
-this section) that SmartSim ships with, modify as needed, and then use ``smart
-build --config-dir`` to specify the path to your custom configuration(s).
+To customize the version of a backend and/or package, we recommend that you use
+a configuration shipped with SmartSim as a template (for example the one at the
+end of this section). Copy the file and update as needed. Afterwards, use
+``smart build --config-dir`` to tell the build process to use custom
+configuration(s).
 
 The following table describes the main fields needed to define a machine learning
 backend used by RedisAI.

doc/installation_instructions/troubleshooting/offline.rst

@@ -1,9 +1,9 @@
 Airgapped Systems
 -----------------
 
-SmartSim implictly assumes that dependencies can be retrieved via the Internet.
-The ``smart build`` step can be bypassed by transferring the build artifacts
-from a different machine.
+SmartSim assumes that dependencies can be retrieved via the Internet.  The
+``smart build`` step can be bypassed by transferring the build artifacts from a
+different machine.
 
 .. warning::
 
@@ -13,10 +13,12 @@ from a different machine.
     <https://redis.io/legal/rsalv2-agreement/>`_).
 
 
-The easiest way to accomplish this assumes that you have a machine that can be
-connected to the internet and has built SmartSim (referred to as Machine A).
-This machine should have a similar compilation and build environment as the
-target machine (referred to as Machine B) to ensure compatibility.
+The easiest way to accomplish this assumes that you have the following
+- A source machine connected to the internet with SmartSim built (referred to as Machine A).
+- A target machine not connected to the Internet
+
+.. warning::
+    The build and compilation environments of Machine A and B must be compatibile.
 
 **Step 1:** Note the path to SmartSim's ``core`` directory on Machine A
 

doc/installation_instructions/troubleshooting/troubleshooting.rst

@@ -3,9 +3,9 @@
 Installation Troubleshooting
 ============================
 
-SmartSim has been installed on a variety of systems and our users often have
-different build environments and toolchains. The following two sections detail
-some common situations and how to setup and modify your build environment:
+SmartSim has been installed on a variety of systems with different build
+environments and toolchains. The following two sections detail some common
+situations and how to configure your build environment:
 
 .. include:: generic.rst