Creating onboarding and learning resources

[lheagy]

In a related vein to #11, @fperez and I were talking a bit about what are some specific pieces that might be worth centralizing into a tightly scoped JupyterBook targeted at introducing scientists to Jupyter. We started sketching out an outline and a few ideas here:

https://docs.google.com/document/d/12FhikrklL-q86SW5DqbQHd_Yx3k6RnFxhBLuPLkmogQ/edit#

Please feel free to add your thoughts!

[choldgraf]

Who do you imagine to be the target audience of the book? Earth scientists in general? Earth scientists specifically working on Pangeo infrastructure? (or 2i2c-style infrastructure?). Related to that is how this would relate to the other materials that are out there for beginners that may already utilize Jupyter etc (e.g. on the domain side Pangeo has a ton of tutorials, there's geosci.xyz, earthlab, etc - on the tech side there are a billion "intro to jupyter" materials out there as well as generic data science tutorials).

I think the more that a specific niche can be defined for this content compared with what is already out there, the more impactful it could be. Right now the "signal to noise" of content for learning Jupyter/python/etc is not super high because there is just so much material out there.

[lheagy]

Good questions Chris. The persona that I have in mind that we talked about is "A [Earth Science] researcher who has experience with computation [Matlab / Fortran / ...] and is interested in using Jupyter + python and doesn't know where to start." I don't think it is within scope here to be teaching python, but rather to point in an opinionated way to other resources (e.g. those in progress with Pythia, cc @kmpaul), and to be the ones to generate some of the Jupyter specific content. Do you think this is a tight enough scope?

Another question I have is where we would like to host these? I would be inclined at this stage to just develop them in this repo here, and if it grows our of scope, move elsewhere then. Would that work with folks?

[lheagy]

I started putting some scaffolding in place and would appreciate input and suggestions from folks on if this outline flows and seeing what you think of the level of content in a few places. We can chat further at the meeting on Monday. The landing page is here

• each landing page for the three sections contains a "Purpose" and a short summary of what is included in the section
  • introduction
  • tools in the Jupyter ecosystem
  • broader ecosystem

A few pages that I have made a start on that would be great to get feedback / ideas on:

• widgets
• managing state: this is short right now, but hearing other examples of "gotchas" would be great
• binder

Questions

• is this the right level of information?
• are there other topics that you think we are missing?
• any other suggestions on flow / content specifically thinking of researchers as the primary target audience?

[lheagy]

@kafonek: we have talked a bit about coding practices in the notebook, I would be curious what other gotcha-examples come to mind on the managing state page

[lheagy]

We have an outline + initial content in place for this. Below, I provide an update of where each page is at. For a quick overview I use

• [0]: template created, no content yet
• [1]: initial pass at some content, still needs to be fleshed out
• [2]: content relatively complete, still could benefit from review, possible video
• [3]: content basically complete, review + improvements still always welcome!

Introduction

• [0] Jupyter overview: template created, no content
• [2] Ecosystem: content created, initial review from @whyjz (#33)
• [2] A tour of Jupyter: page + initial content created, might benefit from a video

Tools in the Jupyter Ecosystem

• [2] Jupyter Notebook: content created and adapted from ICESat-2 hackweek. No video yet
• [1] JupyterLab: lightweight initial page created, video included from JupyterLab documentation
• [2] IPython: content created and adapted from ICESat-2 hackweek. No video yet
• [0] IPython Customization: template created, no content
• [3] Jupyter Widgets: content + video recording created
• [1] Managing State: initial content created, could benefit from additional examples
• [1] JupyterHub: initial content created, could benefit from @consideRatio's input!
• [2] Binder: content created, relatively complete, could benefit from review
• [0] JupyterBook: template created, no content

Examples from the broader ecosystem

For the following, only templates have been created, they have not yet been populated with content

• [0] Data structures
• [0] Visualization
• [0] Dashboards
• [0] Intake
• [0] Dask

[kafonek]

@lheagy you could add a link to the famous Joel Grus talk for a light-hearted take on "state" gotchas. Perhaps also suggest that a good mantra for Notebook developers to take is, "restart and run all or it doesn't count." That's one of my first steps in any kind of debug, and often highlights state issues that otherwise leave you scratching your head.

State management hits beginners the hardest, so it's worth addressing early on. In the grand scheme of things, I didn't see simple state management as a particularly large pain point in our community. When really confusing issues have popped up, like "why were these parameters/syntax submitted to this API (creating an audit incident)???" then it was always accompanied by complicated and convoluted dozens-or-hundreds-of-lines-in-one-cell code. I'm not sure how to distill that lesson learned down into a concise example, but I would consider linking readability / literate programming with state management.