Add video supplement for "How to Use This Book"
Opened this issue · 13 comments
@ncorbin-id, #76 has been merged. How would you like to proceed with the video?
@clyne First I will take what you've written and create a script from it along with a proof-of-concept video. Then I'll take your comments and feedback on that and create a more polished version, which may or may not end up being final. It's important that we get any script or wording issues taken care of before that second iteration of the video since re-recording and editing audio is a non-trivial task.
I say this with the caveat that I need to get a few Unidata projects out the door first, so I'm looking at the week of Sept 20 to have a script and POC video ready for your review. Given that I'm assuming the video will be supplemental to the content that's already written, I'm hoping that won't be too much of a stretch. But please let me know if that would be an issue.
One initial question for you, are you hoping that the video will cover the entire contents of "How to Use This Book" or just the "Running Pythia Foundation examples" section? I'm leaning towards the latter in case the organization of the book ever changes.
@clyne First I will take what you've written and create a script from it along with a proof-of-concept video. Then I'll take your comments and feedback on that and create a more polished version, which may or may not end up being final. It's important that we get any script or wording issues taken care of before that second iteration of the video since re-recording and editing audio is a non-trivial task.
I say this with the caveat that I need to get a few Unidata projects out the door first, so I'm looking at the week of Sept 20 to have a script and POC video ready for your review. Given that I'm assuming the video will be supplemental to the content that's already written, I'm hoping that won't be too much of a stretch. But please let me know if that would be an issue.
Sounds great. No rush.
One initial question for you, are you hoping that the video will cover the entire contents of "How to Use This Book" or just the "Running Pythia Foundation examples" section? I'm leaning towards the latter in case the organization of the book ever changes.
Agreed!
The first draft of the script is complete and ready for comment. I've drafted it in Google docs for direct commenting, and I already have a few questions for y'all in there already.
https://docs.google.com/document/d/1yD8q63KEei5sDCOW_mNI4Ncadli4SpRBUceVbXYa4Rk/edit?usp=sharing
I'll also set the expectation again that modifying the wording of the script at this stage is very important since changing wording after the voiceover is recorded is a lot of work.
Looks great, @ncorbin-id. Please see my in-line reviews. cc'ing @brian-rose
Just finished going through and left inline comments in the doc.
I'd love to resolve two issues before we proceed:
- what's the name of the book? Thanks @ncorbin-id for identifying the inconsistency. I opened a new issue for this #176
- Basic workflow for users who want to "download and run notebooks locally".
On point 2, my concern is that running notebooks requires a python / conda environment, and we don't really have clear instructions on how to set that up short of cloning the whole repo and using our environment.yml file. And of course once you clone the repo, you have all the notebooks.
I think we need to make a choice, are we going to
- encourage new users to download and run individual notebooks, in which case we need clear instructions on how to set up a stand-alone Pythia Foundations run environment
- or instead, encourage people to clone the repo, use the included
environment.ymlfile to set up their environment, and use git branches to make modifications to notebooks.
Neither one is perfect. For new and casual users, it would nice if there was a more "one click" method for setting up a local conda environment.
It seems that the first choice (bullet 1) would be slightly preferable. It's what we've documented. We've already provided an icon to download individual notebooks. And it would seem a slightly lower barrier for users to have to run a one-time command to set up their environment appropriately, rather than to have them clone a repo, find the notebook in the repo, and then also set up their environment correctly. The IWG folks should weigh in on this (cc @andersy005, @dopplershift)
Well, we could post instructions that point out how to create the environment without cloning like:
conda env create -f https://raw.githubusercontent.com/ProjectPythia/pythia-foundations/main/environment.yml
In that case we might want a more stripped-down environment file to point to (we can have multiple in the repo), since the one I pointed to above has all the dependencies necessary to build the site, not just run a notebook. Of course, the flip side is making sure that second environment stays correct and up-to-date...
Well, we could post instructions that point out how to create the environment without cloning like:
conda env create -f https://raw.githubusercontent.com/ProjectPythia/pythia-foundations/main/environment.yml
I suspect that this is the right approach. We give users a straightforward way to set up a working environment without worrying whether they know how to git clone a repo.
We had a related discussion about environments in #56 (with no particular resolution). If we settle on this approach, then I think it makes sense to maintain two different environment files as @dopplershift suggests.
As for keeping the run environment up-to-date, it should be possible to set up some additional CI for this.
Perhaps this can be discussed at the IWG meeting this week and we can figure out a path forward that would allow us to complete the video.
Hey y'all, a few pending questions on this for you to make sure I have the story straight:
- Is downloading a single chapter as an ipynb still an option for the user?
- If yes, then will the user create the environment from an environment.yml file or will they need to clone the whole repo?
- Where will the written instructions for the above workflow live in the book?
With those answers I'll fix up the script and send it back for additional comment.
@ncorbin-id, we've discussed this at a few working group meetings, and I think we've settled on a strategy. In response to your questions:
- Yes. The download button will remain on each book page.
- Instructions for how to create a run-time environment (using @dopplershift's suggested approach above) will be prominently found in the "How to Use This Book" section. This will use the same
environment.ymlin the source repo so it will run all our notebooks, but the user will not need to understand anything about cloning to make this work. - Good question. I don't think we even have an open issue for this currently. But it's a relatively easy lift so I can try to put something together this week.
Yes to 1 and 2. The instructions have been added to 'how-to-use' this book, in the yet-to-be merged PR, #199
Hi @ncorbin-id, just checking in to see what the status is on this. It looks like we've merged #199, mentioned above. Thanks!