Better overviews

appendix/glossary.md

@@ -47,13 +47,13 @@ discussions
 documentation
 : Software documentation is descriptive content (e.g., text, images, videos) that is either embedded in the software code or distributed alongside the corresponding software.
 
-Feature Branch Workflow
+feature branch workflow
 : A collaborative development workflow where new development takes place on dedicated branches rather than the main branch.
 
 fork
 : A copy of another project hosted on a collaborative development platform such as {term}`GitHub`.
 
-Forking Workflow
+forking workflow
 : A collaborative development workflow where new development takes place on forked repositories rather than the main project repository.
 
 free and open-source software

appendix/how-to-contribute.md

@@ -3,9 +3,11 @@
 General information on how to contribute to any Project Pythia repository
 may be found in the [Contributing to Project Pythia](https://projectpythia.org/contributing) guide.
 
-As GitHub Pull Requests are an important part of contributing to Pythia, this guide will cross-reference tutorials on GitHub and Pull Requests.
+As GitHub {term}`pull request`s are an important part of contributing to Pythia, this guide will cross-reference tutorials from our chapters on [Getting Started with GitHub](../foundations/getting-started-github.md).
 
-If you need to comment on anything in Pythia Foundations you feel needs work, you can use the "open issue" or "suggest edit" buttons at the top of any Pythia Foundations page. These buttons appear when you hover over the GitHub Octocat logo. Clicking on these buttons will take you to the relevant page on GitHub, where the entirety of the Pythia Foundations material is hosted. In order to actually suggest changes, you must have a free GitHub account, as listed in the GitHub section of Pythia Foundations. This guide is strictly for Pythia Foundations; for general Project Pythia contribution guidelines, see the main guide for [Contributing to Project Pythia](https://projectpythia.org/contributing).
+A quick and easy way to find the Pythia Foundations source repository on GitHub while you are browsing the book is to look for the GitHub Octocat logo near the top right of each page. This will link directly to our [main source repository on GitHub](https://github.com/ProjectPythia/pythia-foundations).
+
+In order to [open issues](../foundations/github/github-issues.md) or create [pull requests](../foundations/github/github-pull-request.md) to suggest changes, you must have a [free GitHub account](../foundations/github/what-is-github.md). This guide is strictly for Pythia Foundations; for general Project Pythia contribution guidelines, see the main guide for [Contributing to Project Pythia](https://projectpythia.org/contributing).
 
 To quickly provide feedback about minor issues without the use of GitHub, you can also use this [Google Form](https://docs.google.com/forms/d/e/1FAIpQLSeVa1TC9xM-dk7qIE2e8bsgSrIP82yYDNw3wew3J46eREJa4w/viewform?usp=sf_link).
 

appendix/template.ipynb

@@ -40,13 +40,17 @@
    "metadata": {},
    "source": [
     "## Overview\n",
-    "If you have an introductory paragraph, lead with it here! Keep it short and tied to your material, then be sure to continue into the required list of topics below,\n",
+    "If you have an introductory paragraph, lead with it here! Keep it short and tied to your material.\n",
+    "\n",
+    "Optionally, you can include an ordered list of topics like these.\n",
     "\n",
     "1. This is a numbered list of the specific topics\n",
     "1. These should map approximately to your main sections of content\n",
     "1. Or each second-level, `##`, header in your notebook\n",
     "1. Keep the size and scope of your notebook in check\n",
-    "1. And be sure to let the reader know up front the important concepts they'll be leaving with"
+    "1. And be sure to let the reader know up front the important concepts they'll be leaving with\n",
+    "\n",
+    "This list is not always needed, since an in-page navigation bar using your section headings will be created automatically when the book is rendered."
    ]
   },
   {

core/matplotlib/annotations-colorbars-layouts.ipynb

@@ -12,15 +12,7 @@
     "---\n",
     "## Overview\n",
     "\n",
-    "In this section we explore methods for customizing plots.  The following topics will be covered:\n",
-    "\n",
-    "1. Adding annotations\n",
-    "1. Rendering equations\n",
-    "1. Colormap overview \n",
-    "1. Basic colorbars \n",
-    "1. Shared colorbars\n",
-    "1. Custom colorbars\n",
-    "1. Mosaic subplots"
+    "In this chapter we explore some more advanced methods for customizing plots. We will start with adding **text annotations** and **rendered math** with LaTeX. We then explore some details of **colormaps** and **colorbar** customization. Finally, we take a look at the **mosaic subplot**, a simple method for customizing the layout of multi-plot figures."
    ]
   },
   {

core/matplotlib/histograms-piecharts-animation.ipynb

@@ -18,11 +18,7 @@
     "---\n",
     "## Overview\n",
     "\n",
-    "In this section we'll explore some more specialized plot types, including:\n",
-    "\n",
-    "1. Histograms\n",
-    "1. Pie Charts\n",
-    "1. Animations"
+    "In this chapter we'll explore some more specialized plot types, including **histograms** and **pie charts**. We will then introduce Matplotlib's **animation** toolkit, which lets us create animations from functions."
    ]
   },
   {

core/matplotlib/matplotlib-basics.ipynb

@@ -16,17 +16,11 @@
    "metadata": {},
    "source": [
     "## Overview\n",
-    "We will cover the basics of using the Matplotlib {cite:p}`Hunter:2007` library to create plots in Python, including a few different plots available within the library. This page is laid out as follows:\n",
-    "\n",
-    "1. Why Matplotlib?\n",
-    "1. Figure and axes\n",
-    "1. Basic line plots\n",
-    "1. Labels and grid lines\n",
-    "1. Customizing colors\n",
-    "1. Subplots\n",
-    "1. Scatterplots\n",
-    "1. Displaying Images\n",
-    "1. Contour and filled contour plots."
+    "This chapter will cover the basics of using the Matplotlib {cite:p}`Hunter:2007` library to create plots in Python. \n",
+    "\n",
+    "We will start with the core Matplotlib concepts of **Figures** and **Axes**. We'll then make some basic **line plots** from arrays of data and walk through some customization options like **labels**, **grid lines**, and **colors**. Next, we will discuss combining multiple plots into a single figure with **subplots** and show how to share an axis between two plots.\n",
+    "\n",
+    "Finally, we will explore some other common plot types, including **scatterplots**, **image** plots, and **contour** plots."
    ]
   },
   {

core/numpy/intermediate-numpy.ipynb

@@ -19,9 +19,8 @@
    "metadata": {},
    "source": [
     "## Overview\n",
-    "1. Working with multiple dimensions\n",
-    "1. Subsetting of irregular arrays with booleans\n",
-    "1. Sorting, or indexing with indices"
+    "\n",
+    "This chapter will introduce some of NumPy's more advanced capabilities, with a focus on using indexing operations to manipulate arrays of numbers. We'll look first at basic ordered indexing of arrays with multiple dimensions and some vector operations. Then we'll look at subsetting arrays using boolean logic and finally using array indexing operations for sorting and subsetting."
    ]
   },
   {

core/overview.md

@@ -74,7 +74,7 @@ greatly simplifies the code development process (read: less lines of code).
 
 One of the limitations of Pandas
 is that it’s only able to handle one- or two-dimensional (i.e. tabular) data arrays.
-The [Xarray](http://xarray.pydata.org/) library was therefore created
+The [Xarray](https://docs.xarray.dev/) library was therefore created
 to extend the labelled array concept to N-dimensional arrays:
 
 ![Xarray Dataset schematic](https://github.com/pydata/xarray/blob/5f670a74392e3b625dba283c75c6dc2a43be808b/doc/_static/dataset-diagram.png)

core/pandas/pandas.ipynb

@@ -21,9 +21,8 @@
    "metadata": {},
    "source": [
     "## Overview\n",
-    "1. Introduction to pandas {cite:p}`reback2020pandas` data structures\n",
-    "1. How to slice and dice pandas dataframes and dataseries\n",
-    "1. How to use pandas for exploratory data analysis\n",
+    "\n",
+    "This chapter starts with an introduction to the core pandas {cite:p}`reback2020pandas` structures for labeled tabular data, the `DataFrame` and the `Series`. We will load in some example time series data and explore basic methods for slicing and dicing the data with pandas. We then dig into some exploratory data analysis, including basic statistics, quick plotting, resampling in time, and applying operations to data in a `DataFrame`.\n",
     "\n",
     "## Prerequisites\n",
     "\n",

core/xarray.md

@@ -20,4 +20,4 @@ You should have a basic familiarity with [Numpy arrays](numpy.md) prior to worki
 3 hours
 :::
 
-[xarray home]: http://xarray.pydata.org/en/stable/
+[xarray home]: https://docs.xarray.dev/en/stable/

core/xarray/computation-masking.ipynb

@@ -870,16 +870,22 @@
    "source": [
     "## Additional resources\n",
     "\n",
-    "- `groupby`: [Useful for binning/grouping data and applying reductions and/or transformations on those groups](https://xarray.pydata.org/en/stable/user-guide/groupby.html)\n",
-    "- `resample`: [Functionality similar to groupby, specialized for time dimensions. Can be used for temporal upsampling and downsampling](https://xarray.pydata.org/en/stable/user-guide/time-series.html#resampling-and-grouped-operations)\n",
-    "- `rolling`: [Useful for computing aggregations on moving windows of your dataset, e.g., computing moving averages](https://xarray.pydata.org/en/stable/user-guide/computation.html#rolling-window-operations)\n",
-    "- `coarsen`: [Generic functionality for downsampling data](https://xarray.pydata.org/en/stable/user-guide/computation.html#coarsen-large-arrays)\n",
+    "- `groupby`: [Useful for binning/grouping data and applying reductions and/or transformations on those groups](https://docs.xarray.dev/en/stable/user-guide/groupby.html)\n",
+    "- `resample`: [Functionality similar to groupby, specialized for time dimensions. Can be used for temporal upsampling and downsampling](https://docs.xarray.dev/en/stable/user-guide/time-series.html#resampling-and-grouped-operations)\n",
+    "- `rolling`: [Useful for computing aggregations on moving windows of your dataset, e.g., computing moving averages](https://docs.xarray.dev/en/stable/user-guide/computation.html#rolling-window-operations)\n",
+    "- `coarsen`: [Generic functionality for downsampling data](https://docs.xarray.dev/en/stable/user-guide/computation.html#coarsen-large-arrays)\n",
     "\n",
-    "- `weighted`: [Useful for weighting data before applying reductions](https://xarray.pydata.org/en/stable/user-guide/computation.html#weighted-array-reductions)\n",
+    "- `weighted`: [Useful for weighting data before applying reductions](https://docs.xarray.dev/en/stable/user-guide/computation.html#weighted-array-reductions)\n",
     "\n",
     "- [More xarray tutorials and videos](https://docs.xarray.dev/en/stable/getting-started-guide/tutorials-and-videos.html)\n",
-    "- [Xarray Documentation - Masking with `where()`](https://xarray.pydata.org/en/stable/user-guide/indexing.html#masking-with-where)\n"
+    "- [Xarray Documentation - Masking with `where()`](https://docs.xarray.dev/en/stable/user-guide/indexing.html#masking-with-where)\n"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8effc651",
+   "metadata": {},
+   "source": []
   }
  ],
  "metadata": {

core/xarray/dask-arrays-xarray.ipynb

@@ -12,8 +12,9 @@
     ":align: left\n",
     "```\n",
     "\n",
+    "## Overview\n",
     "\n",
-    "The scientific Python package known as Dask [@https://doi.org/10.25080/Majora-7b98e3ed-013] provides Dask Arrays: parallel, larger-than-memory, n-dimensional arrays that make use of blocked algorithms. They are analogous to Numpy arrays, but are distributed. These terms are defined below:\n",
+    "The scientific Python package known as Dask [@https://doi.org/10.25080/Majora-7b98e3ed-013] provides Dask Arrays: parallel, larger-than-memory, n-dimensional arrays that make use of blocked algorithms. They are analogous to NumPy arrays, but are distributed. These terms are defined below:\n",
     "\n",
     "*  **Parallel** code uses many or all of the cores on the computer running the code.\n",
     "*  **Larger-than-memory** refers to algorithms that break up data arrays into small pieces, operate on these pieces in an optimized fashion, and stream data from a storage device. This allows a user or programmer to work with datasets of a size larger than the available memory.\n",

core/xarray/xarray-intro.ipynb

@@ -105,7 +105,7 @@
    "source": [
     "### Creation of a `DataArray` object\n",
     "\n",
-    "The `DataArray` in one of the most basic elements of Xarray; a `DataArray` object is similar to a numpy `ndarray` object. (For more information, see the documentation [here](http://xarray.pydata.org/en/stable/user-guide/data-structures.html#dataarray).) In addition to retaining most functionality from NumPy arrays, Xarray `DataArrays` provide two critical pieces of functionality:\n",
+    "The `DataArray` in one of the most basic elements of Xarray; a `DataArray` object is similar to a NumPy `ndarray` object. (For more information, see the documentation [here](https://docs.xarray.dev/en/stable/user-guide/data-structures.html#dataarray).) In addition to retaining most functionality from NumPy arrays, Xarray `DataArrays` provide two critical pieces of functionality:\n",
     "\n",
     "1. Coordinate names and values are stored with the data, making slicing and indexing much more powerful.\n",
     "2. Attributes, similar to those in netCDF files, can be stored in a container built into the `DataArray`.\n",

foundations/getting-started-python.md

@@ -8,5 +8,8 @@
 
 ## Topics
 
-- [Quickstart: Zero to Python](quickstart): For the impatient among us: run your first Python code in the cloud!
-- [Installing and Running Python](how-to-run-python): Detailed instructions for choosing a Python platform and getting up and running on a laptop, including using the conda package manager.
+- [Quickstart: Zero to Python](quickstart.ipynb): For the impatient among us: run your first Python code in the cloud!
+- [Choosing a Python Platform](how-to-run-python.md): A brief overview of different ways to run Python code.
+- [Python in the Terminal](terminal.md): A quickstart guide to installing and running Python in a terminal.
+- [Python in Jupyter](jupyter.md): A quickstart guide to installing and running Python in a {term}`Jupyter Notebook`.
+- [Installing and Managing Python with Conda](conda.md): A detailed guide to the {term}`conda` package manager and installation with {term}`Miniforge`.

foundations/github/basic-git.md

@@ -7,10 +7,9 @@
 
 ## Overview
 
-1. The need for version control
-1. Basic Git usage
-1. Making your first Git commit
-1. Viewing and comparing across the commit history
+Now that we've covered some basic GitHub features and configured your account appropriately, it's time to take a deeper dive in {term}`version control` and {term}`Git`, our recommended VCS. We'll discuss the need for version control and explain the relationship between Git (the VCS software) and GitHub (the web-based code-hosting and collaboration platform).
+
+We'll then lead you through some basic Git usage, including making your first Git commit (registering changes to source code) and viewing / comparing across the commit history of a repository.
 
 ## Prerequisites
 

foundations/github/contribute-to-pythia.md

@@ -5,11 +5,9 @@
 :width: 400px
 ```
 
-## Overview:
+## Overview
 
-1. Suggest a change
-2. Make the edits
-3. Create a pull request
+Now that you have become more familiar with how to use {term}`Git` and {term}`GitHub`, you might have an idea or some material that you want to contribute to Project Pythia! The [Project Pythia Contributor's Guide](https://projectpythia.org/contributing) describes the steps required to submit a PR to any of Project Pythia's repos. Here, we will go through an example of creating and submitting a PR to the `pythia-foundations` repository, i.e., the source code for the pages you are browsing right now!
 
 ## Prerequisites
 
@@ -31,8 +29,6 @@
 
 ---
 
-Now that you have become more familiar with how to use Git and GitHub, you might have an idea or some material that you want to contribute to Project Pythia! The [Project Pythia Contributor's Guide](https://projectpythia.org/contributing) describes the steps required to submit a PR to any of Project Pythia's repos. Here, we will go through an example of submitting a PR to the `pythia-foundations` repository.
-
 ## Suggest a change
 
 One simple way to contribute is to fix a typo or suggest a change to one of the tutorials. For example, in the [Computations and Masks with Xarray tutorial](../../core/xarray/computation-masking), let's suggest a clarification that the sea surface temperature is called `tos` in the dataset we are using.

foundations/github/git-branches.md

@@ -5,18 +5,13 @@
 :width: 400px
 ```
 
-Git "branches" are an important component of many Git and GitHub workflows. If you plan to use GitHub to manage your own resources, or contribute to a GitHub hosted project, it is essential to have a basic understanding of what branches are and how to use them. For example, the best practices for a simple workflow for suggesting changes to a GitHub repository are: create your own fork of the repository, make a branch from your fork where your changes are made, and then suggest these changes move to the upstream repository with a Pull Request. This section of the GitHub chapter assumes you have read the prior GitHub sections, are at least somewhat familiar with git commands and the vocabulary ("cloning," "forking," "merging," "Pull Request" etc), and that you have already created your own fork of the [GitHub Sandbox Repository](https://github.com/ProjectPythia/github-sandbox) hosted by Project Pythia.
-
-## Overview:
-
-1. What are Git branches
-1. Creating a new branch
-1. Switching branches
-1. Setting up a remote branch
-1. Merging branches
-1. Deleting branches
-1. Updating your branches
-1. Complete workflow
+## Overview
+
+Git **branches** are an important component of many {term}`Git` and {term}`GitHub` workflows. If you plan to use GitHub to manage your own resources, or contribute to a GitHub hosted project, it is essential to have a basic understanding of what branches are and how to use them. For example, the best practices for a simple workflow for suggesting changes to a GitHub repository are: create your own {term}`fork` of the repository, make a {term}`branch` from your fork where your changes are made, and then suggest these changes move to the upstream repository with a {term}`pull request`.
+
+This chapter assumes you have read the prior GitHub content, are at least somewhat familiar with Git commands and the vocabulary ({term}`clone`, {term}`fork`, {term}`merge`, {term}`pull request`), and that you have already created your own fork of the [GitHub Sandbox Repository](https://github.com/ProjectPythia/github-sandbox) hosted by Project Pythia.
+
+We will first discuss some basics about what branches are. Then we'll lead you through creating a new branch, switching between branches, setting up remote branches (connections between code on your laptop and code on GitHub), and practice some merging, deleting, and updating of branches.
 
 ## Prerequisites
 

foundations/github/git-workflows.md

@@ -5,13 +5,11 @@
 :width: 400px
 ```
 
-A workflow is a series of activities or tasks that must be completed sequentially or parallel to achieve the desired outcome. Here we outline two different Git workflows that take you through the steps leading up to opening a pull request.
+## Overview
 
-## Overview:
+A workflow is a series of activities or tasks that must be completed sequentially or parallel to achieve the desired outcome. Here we explain and walk you through two different {term}`Git` workflows that take you through the steps leading up to opening a {term}`pull request`: the {term}`feature branch workflow` and the {term}`forking workflow`.
 
-1. Overview of Git workflows
-1. Feature branch workflow
-1. Forking workflow
+Understanding these two workflows (and how they differ from each other) is very helpful for contributing to collaborative open source projects.
 
 ## Prerequisites