DOI-USGS · jrcain-usgs · Mar 5, 2025 · Mar 5, 2025 · Mar 5, 2025 · Mar 5, 2025
diff --git a/...ow-to-guides/environment-setup-and-maintenance/adding-usgscsm-plugin-to-isis.md b/...ow-to-guides/environment-setup-and-maintenance/adding-usgscsm-plugin-to-isis.md
@@ -1,7 +1,7 @@
-# Adding USGSCSM Plugin to ISIS
+# Adding the USGSCSM Plugin to ISIS ≤ 8.1
 
-???+ warning
-      Upcoming ISIS version 8.2 and future releases will include the USGSCSM library and does __not__ require a separate installation of the plugin.
+!!! warning "Only needed for ISIS 8.1 and earlier" 
+      ISIS versions 8.2 and later include the USGSCSM library and do __not__ require a separate installation of the plugin.
 
       ISIS versions 8.0LTS, 8.1, and earlier _require_ a separate installation of the USGSCSM plugin as shown below.
 
@@ -14,8 +14,8 @@ conda install conda-forge::usgscsm
 
 ## For developers
 
-???+ info
-    For USGSCSM versions 2.0 and above, the plugin is installed in `$CONDA_PREFIX/lib/csmplugins/` in an Anaconda environment.
+???+ info "Plugin Install Location"
+    For USGSCSM versions 2.0 and above, the plugin is installed in `$CONDA_PREFIX/lib/csmplugins/` in a conda environment.
 
 ### Plugin setup
 If you are testing a new plugin or using older versions of USGSCSM/ISIS, you will need to update your `IsisPreferences` file located under the `ISIS3/isis` directory with the appropriate plugin path change. 

diff --git a/...o-guides/environment-setup-and-maintenance/anaconda-in-a-network-environment.md b/...o-guides/environment-setup-and-maintenance/anaconda-in-a-network-environment.md
@@ -1,5 +1,9 @@
 # Creating a shared Anaconda installation
 
+!!! info "Internal Procedures"
+
+    This document is intended primarily for internal use at the USGS Astrogeology Science center.  It details setup that is specific to our internal network.  It is likely not very useful for those who don't either work for the USGS ASC or have access to our network.
+
 ## Introduction
 
 Here at the USGS Astrogeology Science Center (ASC) we have a software development team consisting of roughly a dozen full or part time developers, another dozen or so technical users, and a few dozen scientists who all need consistent access to software builds and releases. As we moved to using Anaconda for dependency management and software installation, our IT group quickly flagged an issue where users' Home directories were growing astronomically large from each having their own Anaconda installation. Along with that, we had many users who had never used Anaconda before having to manage and debug their own installations. Fairly quickly, we settled upon having shared Anaconda installations that users could access and use across systems without having to manage their own Anaconda installation or update their environments.

diff --git a/...how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md b/...how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md
@@ -1,5 +1,12 @@
 # Installing ISIS
 
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: __Introduction__ to ISIS](../../getting-started/using-isis-first-steps/introduction-to-isis.md)
+- [:octicons-arrow-right-24: Setting up the  __ISIS Data Area__](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md)
+
+</div>
+
 ## Prerequisites
 
 ??? "Conda"

diff --git a/docs/how-to-guides/environment-setup-and-maintenance/isis-data-area.md b/docs/how-to-guides/environment-setup-and-maintenance/isis-data-area.md
@@ -1,5 +1,12 @@
 # Setting Up the ISIS Data Area
 
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: __Installing__ ISIS](../../how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md)
+- [:octicons-arrow-right-24: SPICE Kernel __Updates__](../../how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md)
+
+</div>
+
 Many ISIS apps need extra data to carry out their functions.  This data varies depending on the mission, and may be **quite large**, so it is **not included** with the ISIS binaries. It resides in the **ISIS Data Area**.
 
 ??? info "More Info on the ISIS Data Area"

diff --git a/...how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md b/...how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md
@@ -1,3 +1,12 @@
+# SPICE Kernel Updates in ISIS
+
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: Setting up the  __ISIS Data Area__](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md)
+- [:octicons-arrow-right-24: Using ISIS in __other conda envs__](../../how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md)
+
+</div>
+
 SPICE kernels are required for the use of most ISIS applications. ISIS provides SPICE kernels for each mission
 in the [ISIS Data Area](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md).
 

diff --git a/...w-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md b/...w-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md
@@ -1,5 +1,11 @@
 # Using ISIS in other Conda Environments
 
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: Setting up the  __ISIS Data Area__](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md)
+
+</div>
+
 The ISIS conda package pins some of its requirements, 
 which may clash with other packages. 
 

diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md
@@ -1,23 +1,54 @@
 # How-To Guides
 
-How-to guides are much like recipes in a recipe book. Write how-to docs to solve specific problems quickly, sometimes copy-pastable. Think of how-to guides as preemptive StackOverflow-like problems.
+[comment]: <> (These cards are a good place to highlight specific docs with high value, or ones readers commonly want to see)
 
+<div class="grid cards" markdown>
 
-## For Readers 
-[comment]: <> (This is a good place to mention any places for someone to start looking in. Highlight specific docs with high value or we identify readers commonly want to see)
+-   :octicons-download-24:{ .lg .middle } __Ready to use ISIS?__
 
-Use the table of contents on the left to start browsing guides. 
+    ---
 
-## For Authors
+    Install ISIS with `conda` and download data for your mission.
 
-Before you start writing a new How-To guide. Make sure what you are writing belongs here. These are similar to getting-started guides, in that they explain to users how to perform some valuable tasks with the software, but distinct in that they:
+    [:octicons-arrow-right-24: Install ISIS](../how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md)
 
-1. Solve practical problems for more experienced users
-1. Offer more ambiguous starting points; they should be reusable in many different contexts 
-1. Can be much shorter than getting-started docs. 
+-   :octicons-code-square-24:{ .lg .middle } __ISIS Development Guides__
 
-??? Info Examples
-    * How-to: generate an ISD via loads with specific kernels
-    * How-to: get GEOJSON from ISIS footprints
-    * Cookbook of common operations in a library
+    ---
+
+    Learn how to build, write code for, and contribute to ISIS.
+
+    [:octicons-arrow-right-24: Develop in ISIS](../how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md)
+
+-   :octicons-comment-discussion-24:{ .lg .middle } __I have an Issue!__
+
+    ---
+
+    Learn about how to report issues with ISIS and how the maintainers respond to issues.
+
+    [:octicons-arrow-right-24: Report an Issue](../how-to-guides/software-management/guidelines-for-reporting-issues.md)
+
+</div>
+
+-----
+
+How-to guides are much like recipes in a recipe book. They show how to carry out a specific task quickly, and can be copy-pastable. Think of how-to guides as preemptive StackOverflow-like answers.
+
+Use the table of contents on the left to start browsing guides.  Check out the above cards if you aren't sure where to start.  Use the search bar if you're looking for something specific.
+
+-----
+
+??? quote "Want to write a how-to guide?"
+
+    When contributing documentation, consider what category it should should go in.  Docs in the **how-to guides** category should: 
+
+    1. Solve practical problems for more experienced users
+    1. Offer more ambiguous starting points; they should be reusable in many different contexts 
+    1. Can be much shorter than getting-started docs
+    1. Some examples:
+        - How-to: generate an ISD via loads with specific kernels
+        - How-to: get GEOJSON from ISIS footprints
+        - Cookbook of common operations in a library
+
+    On the other hand, docs in the **getting started** category detail specific tasks for users who may not have much experience; docs in the **concepts** category provide an understanding of a topic without necessarily going into detail on how to carry out specific tasks. 
 
diff --git a/docs/how-to-guides/isis-developer-guides/app-testing-cookbook.md b/docs/how-to-guides/isis-developer-guides/app-testing-cookbook.md
@@ -1,6 +1,11 @@
+# ISIS App Testing Templates 
 
-# ISIS App Testing Cookbook 
+<div class="grid cards" markdown>
 
+- [:octicons-arrow-left-24: Writing Tests with __CTest and GTest__](../../how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md)
+- [:octicons-arrow-right-24: __Doxygen Tags__ (class requirement)](../../how-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md)
+
+</div>
 
 ### Main.cpp Templates 
 

diff --git a/...w-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md b/...w-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md
@@ -1,4 +1,11 @@
-# Building and Contributing to ISIS Tutorial
+# Contributing to ISIS - Tutorial
+
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: __Contributing to ISIS__: Overview](../../how-to-guides/isis-developer-guides/contributing-to-isis.md)
+- [:octicons-arrow-right-24: Writing Tests with __CTest and GTest__](../../how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md)
+
+</div>
 
 ## 1. Set Up Your Local ISIS Environment
 

diff --git a/...ow-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md b/...ow-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md
@@ -1,4 +1,13 @@
-A new ISIS3 class needs to have the following Doxygen tags filled out just above the class declaration, as in this example below:
+# Doxygen Tags
+
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: __Templates__ for app testing](../../how-to-guides/isis-developer-guides/app-testing-cookbook.md)
+- [:octicons-arrow-right-24: ISIS Programming Exercise: `mirror`](../../how-to-guides/isis-developer-guides/exercise-1.md)
+
+</div>
+
+A new ISIS class needs to have the following Doxygen tags filled out just above the class declaration, as in this example below:
 
 ```C++
    /**

diff --git a/docs/how-to-guides/isis-developer-guides/contributing-to-isis.md b/docs/how-to-guides/isis-developer-guides/contributing-to-isis.md
@@ -1,5 +1,11 @@
-# Contributing to ISIS
-This document serves as a concise guide on how to contribute to ISIS.
+# Contributing to ISIS - Overview
+
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: ISIS __Test Data__](../../how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md)
+- [:octicons-arrow-right-24: __Contributing to ISIS__: Tutorial](../../how-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md)
+
+</div>
 
 ## Build ISIS
 Begin by referring to our [Developing ISIS3 with CMake](./developing-isis3-with-cmake.md) page for instructions on setting up a local clone of ISIS and configuring an Anaconda environment for building. Once you've followed the steps outlined there, you'll have a local build of ISIS ready for development.

diff --git a/docs/how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md b/docs/how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md
@@ -1,3 +1,12 @@
+# Developing ISIS with cmake
+
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: __Introduction__ to ISIS](../../getting-started/using-isis-first-steps/introduction-to-isis.md)
+- [:octicons-arrow-right-24: ISIS __Test Data__](../../how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md)
+
+</div>
+
 ## Getting Started With GitHub
 To get started, you want a fresh copy of ISIS to work on. You first want to create a fork of the ISIS3 repo by going to the [main ISIS3 repo page](https://github.com/DOI-USGS/ISIS3) and clicking on "Fork" at the top of the page.
 

diff --git a/docs/how-to-guides/isis-developer-guides/exercise-1.md b/docs/how-to-guides/isis-developer-guides/exercise-1.md
@@ -1,6 +1,13 @@
-# Exercises 1
+# ISIS Programming Exercise 1: `mirror`
 
-The purpose behind these exercises is to help programmers become familiar with the ISIS3 environment, the ISIS3 API, and ISIS3 standards.
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: __Doxygen Tags__ (class requirement)](../../how-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md)
+- [:octicons-arrow-right-24: ISIS Programming Exercise 2: `diff`](../../how-to-guides/isis-developer-guides/exercise-2.md)
+
+</div>
+
+The purpose behind these exercises is to help programmers become familiar with the ISIS environment, the ISIS API, and ISIS standards.
 
 ## Prerequisites
 

diff --git a/docs/how-to-guides/isis-developer-guides/exercise-2.md b/docs/how-to-guides/isis-developer-guides/exercise-2.md
@@ -1,6 +1,13 @@
-# Exercises 2
+# ISIS Programming Exercise 2: `diff`
 
-The goal of this exercise is to familiarize the programmer with slightly more advanced features of the ISIS3 API. You will be writing an ISIS3 application that performs simple differences between adjacent pixels in the line or sample directions.
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: ISIS Programming Exercise 1: `mirror`](../../how-to-guides/isis-developer-guides/exercise-1.md)
+- [:octicons-arrow-right-24: Start soving issues on __GitHub__ :simple-github:](https://github.com/DOI-USGS/ISIS3/issues)
+
+</div>
+
+The goal of this exercise is to familiarize the programmer with slightly more advanced features of the ISIS API. You will be writing an ISIS application that performs simple differences between adjacent pixels in the line or sample directions.
 
 !!! Info "This tutorial assumes that the user has completed [exercise 1](./exercise-1.md) and has access to the ISIS installation and data from that tutorial."
 

diff --git a/...w-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md b/...w-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md
@@ -1,5 +1,12 @@
 # ISIS Test Data
 
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: __Developing and Building__ ISIS](../../how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md)
+- [:octicons-arrow-right-24: __Contributing to ISIS__: Overview](../../how-to-guides/isis-developer-guides/contributing-to-isis.md)
+
+</div>
+
 ### GTests and Legacy Makefile-based Tests
 
 ISIS has of two types of tests: custom **Makefile** based tests, and **GTests**. The GTests use data from the ISIS repo along with the source, so no special data is required to run those, aside from the ISIS data area.

diff --git a/.../how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md b/.../how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md
@@ -1,4 +1,11 @@
-# How To Write ISIS Tests with CTest and GTest
+# Writing ISIS Tests with CTest & GTest
+
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: __Contributing to ISIS__: Tutorial](../../how-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md)
+- [:octicons-arrow-right-24: __Templates__ for app testing](../../how-to-guides/isis-developer-guides/app-testing-cookbook.md)
+
+</div>
 
 ??? Tip "Helpful External documentation"
 
@@ -22,7 +29,7 @@
     - [ ] New tests passing on Jenkins
     - [ ] Old test data removed
 
-## Refactoring ISIS3 Applications
+## Refactoring ISIS Applications
 
 In order to better integrate with the gtest unit test framework, all of our application logic needs to be callable programmatically.
 

diff --git a/docs/how-to-guides/software-management/deprecation.md b/docs/how-to-guides/software-management/deprecation.md
@@ -1,4 +1,12 @@
 # Deprecation
+
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: __Contribute Fixes__ with Pull Requests](../../how-to-guides/software-management/guidelines-for-pull-requests.md)
+- [:octicons-arrow-right-24: Astro __Software Support Process__](../../how-to-guides/software-management/software-support.md)
+
+</div>
+
 This document is intended to provide guidelines for the deprecation process.
 
 ## 1. Deprecation Proposal

diff --git a/docs/how-to-guides/software-management/guidelines-for-pull-requests.md b/docs/how-to-guides/software-management/guidelines-for-pull-requests.md
@@ -1,5 +1,12 @@
 # Guidelines for Pull Requests
 
+<div class="grid cards" markdown>
+
+- [:octicons-arrow-left-24: __Report an Issue__ on GitHub](../../how-to-guides/software-management/guidelines-for-reporting-issues.md)
+- [:octicons-arrow-right-24: Astro __Software Support Process__](../../how-to-guides/software-management/software-support.md)
+
+</div>
+
 This page provides guidelines for creating a successful pull request.  These guidelines are intended to promote a style of pull request that benefits both the creator of the pull request and the reviewer.
 
 ## PR Creators
@@ -19,6 +26,11 @@ This page provides guidelines for creating a successful pull request.  These gui
 - Ensure that your changes are accompanied by an entry in the changelog
 - Write tests to cover any functionality that is added or changed
 
+-----
+[:octicons-arrow-right-24: See Also: __Deprecation__](../../how-to-guides/software-management/deprecation.md)
+
+-----
+
 
 ### When Creating the Pull Request
 
@@ -40,24 +52,24 @@ Use the following checklist to ensure that your PR follows best practices that w
 
 This section describes best practices for the reviewers of incoming PRs.
 
-### Code Review Checklist
-The purpose of this checklist is to prompt discussion between the reviewer and submitter. Any questions or concerns that come from this checklist should be discussed during the code review.
-
-
-* Does the code work? Does it perform its intended function, the logic is correct etc?
-* Do the changes make sense (in terms of the big picture/ticket/etc.)?
-* Did they complete their developer checklist? Double check their checklist?
-* Does the code include tests?
-* Does the code meet non-functional requirements (scalability, robustness, extensibility, modularity)?
-* Does the code introduce new dependencies?  If so, are they necessary?
-* Is this code in the right place? (are the correct classes/apps handling these things, are they at the right level, does the order make sense)
-* Is there unnecessary duplication in the code or duplication of any code in the repository?
-* Does all this code need to exist? (e.g. extraneous mutators etc.)
-* Are they adding [tech debt](https://www.agileweboperations.com/technical-debt)?
-* Is the code easily understandable (i.e. [squint test](https://robertheaton.com/2014/06/20/code-review-without-your-eyes/))?
-* Does the code handle potential exceptions, return values, invalid inputs...?
-* Is the code needlessly complex?
-* Is there low-hanging fruit that is easily refactorable?
-* Do new classes/functions have well-defined, documented responsibilities? Are these responsibilities too broad?
-* Are the API documentation and comments useful? Are comments explaining why?
-* Are all style choices and changes appropriate?
+???+ abstract "Code Review Checklist"
+
+    The purpose of this checklist is to prompt discussion between the reviewer and submitter. Any questions or concerns that come from this checklist should be discussed during the code review.
+
+    - [ ] Does the code work? Does it perform its intended function, the logic is correct etc?
+    - [ ] Do the changes make sense (in terms of the big picture/ticket/etc.)?
+    - [ ] Did they complete their developer checklist? Double check their checklist?
+    - [ ] Does the code include tests?
+    - [ ] Does the code meet non-functional requirements (scalability, robustness, extensibility, modularity)?
+    - [ ] Does the code introduce new dependencies?  If so, are they necessary?
+    - [ ] Is this code in the right place? (are the correct classes/apps handling these things, are they at the right level, does the order make sense)
+    - [ ] Is there unnecessary duplication in the code or duplication of any code in the repository?
+    - [ ] Does all this code need to exist? (e.g. extraneous mutators etc.)
+    - [ ] Are they adding [tech debt](https://www.agileweboperations.com/technical-debt)?
+    - [ ] Is the code easily understandable (i.e. [squint test](https://robertheaton.com/2014/06/20/code-review-without-your-eyes/))?
+    - [ ] Does the code handle potential exceptions, return values, invalid inputs...?
+    - [ ] Is the code needlessly complex?
+    - [ ] Is there low-hanging fruit that is easily refactorable?
+    - [ ] Do new classes/functions have well-defined, documented responsibilities? Are these responsibilities too broad?
+    - [ ] Are the API documentation and comments useful? Are comments explaining why?
+    - [ ] Are all style choices and changes appropriate?