Open lheagy opened 3 years ago
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.
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?
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
A few pages that I have made a start on that would be great to get feedback / ideas on:
Questions
@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
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
For the following, only templates have been created, they have not yet been populated with content
@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.
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!