CORE: First pass at core package material in one place

[dcamron]

Our Core Scientific Python Packages material as-is

Here is a link to this foundations book rendered on my fork that includes the following open PRs in their current state (Apr 21 2021 ~12:00 MDT) rendered together:

• Initial Cartopy work #24
• Drop in Unidata xarray workshop notebook #33
• Drop in Unidata pandas workshop notebook #34
• Drop in Unidata netcdf+CF notebook for core/data-formats #36
• Drop in Unidata matplotlib workshop notebook #37
• Drop in Unidata datetime intro materials notebook #38
• Drop in Unidata numpy workshop notebooks #39

These represent our first pass at dropping in content to fill out our Core Scientific Python Packages material, including at least one notebook demonstrating each of datetime, NumPy, Matplotlib, pandas, xarray, cartopy, alongside some netCDF/CF material.

My inclination from here is to start this discussion for us to see all these materials in one place so that we can decide what ideas among them we like and want to keep, what we dislike or think doesn't fit, as well as compare their scope, style, and organization so that we can come up the direction for the book's material we want! What material is missing? What material doesn't belong here?

I also think this would be a good hub for capturing discussion to be had synchronously at next week's EWG meeting.

Reviewing the content I've added so far

I'll start with some notes and observations I had common among the Unidata materials I've dropped in this week that we could use to answer questions and inspire decisions. Feel free to take a look through the material yourself first, or skim this and let me know your thoughts:

• Inconsistent title/header style, markdown header levels (important for right navbar population in this theme), linking of headers, inclusion of "to the top" links, naming of similar sections (e.g. References vs. Resources), and general organization of material
• Inconsistent narrative depth and expected knowledge; some of the drop-ins are basically code-comment-led example code with little narrative (e.g. Drop in Unidata numpy workshop notebooks #39 intro numpy), some use thorough text and more complicated examples with more in-depth scientific motivation for intro material (e.g. Drop in Unidata datetime intro materials notebook #38 datetime)
• Similarly, as these were primarily adapted from workshop notebooks, the narrative can be vary around what were previously "exercises" for the class; some of these were designed to be led in a synchronous environment
• Inconsistent scope of covered material, chosen demonstrations, topics considered "important", and how much package crossover is demonstrated or expected up front. Should notebooks be more self-encapsulated with some separate material for their overlap? Should they be overlapping from the start? Thoughts?
• Similarly, how much do we want each of these package chapters to be "units" of separate notebooks or not? How much do we want each package chapter to cover? Jupyter book does give us flexibility for combining individual notebooks into sections
• I personally want to move away from code comments in cells here except where it's a good demonstration to real-world coding and tie these more into the guiding narrative

I have thoughts myself about conclusions from some of these bullet points, but I want to hear from others before I start typing up more rambles!

Let's get this ball rolling

I know it's a lot to chew through, and I think we should have this discussion be a focus for next week's EWG meeting alongside that of some of the new intro material! Take some time to take a look through this material, then I invite people to start sharing thoughts here as soon as possible.

We also can focus on reviewing and merging these PRs individually first and then having this discussion and allowing for people to more easily iterate on their own, whatever workflow y'all prefer. Thanks everyone!

cc @ProjectPythia/education

[brian-rose]

@dcamron this is great! I think this gives us enough content to give a good "bird's eye" view of the material, so that we can effectively ponder the big questions of scope and style.

I hope to devote most of next week's EWG meeting to discussing this. So yes, I encourage everyone to spend some time reviewing the content in detail before that.

[clyne]

This is terrific, @dcamron. It looks really polished and complete. There is a lot of content here, and we should definitely have some discussion on how to effectively and efficiently review. One thing we might also discuss is to what degree we might be able template-ize the books so that we have consistent headers, levels etc., as you mention, but also so we have consistent boiler plate, such as:

1. Logo: every package should have a logo displayed as you have done.
2. Objectives: what the book covers
3. Pre-requisites: what you'll need to know to understand the content
4. Other resources: other sites, internally or externally, that might be helpful
5. Overview: a brief discussion of the topic covered

[dcamron]

Notes from today's meeting for this:

• All agreed on general structure described above by @clyne
• Potentially include wrap-up section at end for "what you have just learned" and "what you can now go do with this"
• Let's use the xarray notebook (Drop in Unidata xarray workshop notebook #33) to review (by next meeting?) to make our "perfect" notebook to then convert to a template @ProjectPythia/education
• Consider the "stand-alone"-ability of these and how to separate them from live teaching materials
  • Designing exercises, expected failures, popouts and tips and notes
  • Creating separate, more interactive exercise material for engagement e.g. via binder; larger discussions here to be had

[dcamron]

With #53 going in, my next step is to revise the un-merged PRs listed here to fit them into the template, and begin responding to content reviews for each one. This might take some time but I will try to prioritize that before the EarthCube annual meeting.

[brian-rose]

Excellent! I suggest we prioritize the numpy content #39 because it comes first in the list, and the PR already has significant discussion.

[dcamron]

With the last of these PRs going in, I'm going to lock this. We can look to open further discussions for iteration, larger-scale content discussions. Thanks everyone for your hard work!