|
| 1 | +# Tutorial Speakers Guide |
| 2 | + |
| 3 | +by **Lorena A. Barba**, JupyterCon 2020 General Chair |
| 4 | + |
| 5 | +## General design |
| 6 | + |
| 7 | +Each tutorial consists of several short pre-recorded videos (<30min each), plus written materials to supplement and expand on the presentations, provided as Jupyter notebooks in the tutorial repository. |
| 8 | + |
| 9 | +During the tutorials week of JupyterCon (5–9 October 2020), pre-recorded videos will air on YouTube Premiere at scheduled times, and tutorial instructors will participate in live discussion with the participants via video conference, also at scheduled times. |
| 10 | +Threaded text chat will be available throughout for all participants and instructors to engage in conversation asynchronously. |
| 11 | +All the videos will remain for on-demand viewing in the JupyterCon YouTube channel after their release. |
| 12 | + |
| 13 | +JupyterCon will build an online course with the materials provided by the instructors, which will remain available after the conference. |
| 14 | +The instructors' content is always open access and free: videos on the JupyterCon YouTube channel, and notebooks in a GitHub repository (under standard public licenses). |
| 15 | +To access the learning sequences on the course platform, however, participants need to be registered. |
| 16 | + |
| 17 | +The written materials must be on Jupyter notebooks because the course building process pulls content directly from notebooks in a GitHub repository to display a learning sequence in the online course platform. |
| 18 | + |
| 19 | +## Speaker commitment: |
| 20 | +The speakers will deliver their prepared materials by **September 11, 2020**, for the JupyterCon team to prepare an online course using the materials, on the JupyterCon learning platform. |
| 21 | +The materials should include an outline that traces a path through the content, with signposts of where each video and other elements (like exercises) should go. |
| 22 | +Speakers will hold “office hours” or "recitations" on a video conference with participants during the tutorials week (5–9 October). |
| 23 | +Speakers are requested to participate in the chat discussions during the tutorials and conference weeks, as their time permits. |
| 24 | + |
| 25 | +## JupyterCon commitment: |
| 26 | +JupyterCon and NumFOCUS volunteers and staff will build the online courses using instructor-created materials. |
| 27 | +All source course material will be publicly available for free (videos on the JupyterCon YouTube channel and Jupyter notebooks on GitHub), but the online courses created in the JupyterCon platform will be accessible to registered participants only. The online course created with the contributed materials will remain after the conference is past, and may continue to be used as micro-learning offering by NumFOCUS. The course platform will embed a discussion forum, using a Mattermost instance provided by NumFOCUS/JupyterCon. |
| 28 | + |
| 29 | +## Infrastructure |
| 30 | + |
| 31 | +JupyterCon has deployed an ecosystem of tools and platforms to provide online learning experiences to all attendees. |
| 32 | +Tutorial instructors will be able to exploit these tools to make their content shine. |
| 33 | + |
| 34 | +### Course platform |
| 35 | + |
| 36 | +We've deployed a full-fledged online course platform, using the [Open edX software](https://open.edx.org/about-open-edx/). |
| 37 | +With speaker-provided materials (video and Jupyter notebooks), JupyterCon volunteers and NumFOCUS staff will build an online course. |
| 38 | +It can include quizzes and auto-graded "homework" exercises, to reinforce the partcipants' learning. |
| 39 | + |
| 40 | +The course platform includes a custom extension that allows creating course content _from any publicly available Jupyter notebook_, using its URL. |
| 41 | +Pulling content from Jupyter notebooks allows us to build a learning sequence from the author-provided content, without duplication. |
| 42 | + |
| 43 | +We also have a custom extension that allows writing exercises for the participants that are tested on-the-fly for correctness. |
| 44 | +This allows creating Jupyter-based "homework" assignments that are auto-graded in the platform. |
| 45 | + |
| 46 | +### JupyterHub/MyBinder |
| 47 | + |
| 48 | +JupyterCon will have a dedicated JupyterHub server that all participants will have access to. |
| 49 | +In addition, we've developed integrations so that it will be possible for tutorial attendees to launch a JupyterHub session with the notebooks provided by the instructor, so they can interact with the computable content. |
| 50 | + |
| 51 | +In your outline, you can specify places in the course content where you want learners to find a "Launch Lab" button, which will launch a Jupyter session with your notebooks pre-loaded. |
| 52 | +You need to provide an environment definition, either in the form on a `requirements.txt` file (for pure Python envionments) or an `environment.yaml` file (for conda environments) at the root of your repository. |
| 53 | + |
| 54 | +### Chat server |
| 55 | + |
| 56 | +[Mattermost](https://mattermost.com) is an open-source, self-hosted "Slack alternative." |
| 57 | +We have deployed a Mattermost server, and integrated it to the course platform via single-sign-on, providing a secure environment for all participants to hold text-based conversations throughout the conference, and beyond. |
| 58 | + |
| 59 | + |
| 60 | +### Video conferencing |
| 61 | + |
| 62 | +The online course platform also includes a custom plug-in that allows us to schedule video calls using our Webex account. |
| 63 | +Participants will be able to join he call with one click from the course. |
| 64 | +This facility will be used for the daily "office hours" or "recitations" with tutorial instructors, scheduled in advance. |
| 65 | + |
| 66 | + |
| 67 | +## Guide to crafting your materials |
| 68 | + |
| 69 | +### Jupyter notebooks |
| 70 | + |
| 71 | +Your tutorial should be written as a set of Jupyter notebooks—at least three or four fully narranted notebooks—walking your reader through the complete path to achieve the learning objectives. |
| 72 | + |
| 73 | +Each Jupyter notebook is "one lesson" and will correspond to "one section" in the online course. |
| 74 | +Printed, it should be 10 to 20 pages, equivalent to 17 to 35 minutes reading time. |
| 75 | +The computational portions should be presented as worked-out examples, broken down into steps, and narrated. |
| 76 | + |
| 77 | +Because the Jupyter notebooks will be ingested into the content management system of the learning platform, to display learning sequences, it is _very important_ that you break up the notebook in sections and sub-sections. |
| 78 | +The section headings, marked by `#`, `##` and so on, will be used as delimiters in the learning sequence to display portions of your notebook. |
| 79 | +That way, the learning sequence can interleave content from the notebooks, videos, self-assessments (e.g., multiple choice quiz), graded Jupyter notebooks, video call schedulers, etc. |
| 80 | + |
| 81 | +In other words, your Jupyter notebooks are like the "textbook," while a learning sequence mixes this content with other experiences or activities. |
| 82 | + |
| 83 | +While we ask that you have a full draft of your notebooks by the delivery date (Sep. 11), you will be able to continue editing the notebooks on GitHub. |
| 84 | +As long as you have provided an accurate outline, and you do not make changes to section and sub-section headings, the course building process can go on in parallel to your final edits. |
| 85 | +The course learning sequences pull content _dynamically_ from the notebooks. |
| 86 | +To be specific: each time a participant visits a section in the course, the Jupyter viewer extension we added to the platform will pull the notebook from its public URL, run `nbconvert`, and display the HTML output. |
| 87 | + |
| 88 | +Building online courses in this way allows us to have the full display richness of Jupyter notebooks: beautiful equations, embedded images in the markdown, syntax-highlighted code, plot outputs, etc. |
| 89 | + |
| 90 | +**Pro tip**: while you are writing your content as Jupyter notebooks, always _clear output_ before pushing to the repository. |
| 91 | +This will facilitate diff-viewing and keep the repo smaller. |
| 92 | +Only push the notebooks with output once you feel they are done. |
| 93 | +If you later fix a typo or make a small edit to markdown cells, push the change without re-running the notebook. |
| 94 | + |
| 95 | +### Videos |
| 96 | + |
| 97 | +We will be working with a media company to provide speakers with support in their creation of high-quality pre-recorded videos. |
| 98 | +These videos can be content-dense, as the live interactions during tutorials week will allow for instructors to guide participants in their learning. |
| 99 | +(Read the [tweet thread by @gregork](https://twitter.com/gregork/status/1291760045269508096) about online videos.) |
| 100 | + |
| 101 | +Your videos can be recorded as a screencast of you live coding and narrating, a slide-based presentation, a camera capture of yourself explaining or narrating some concept, or a mix of all these. |
| 102 | +You can provide video segments and request our media team to post-process, as needed. |
| 103 | + |
| 104 | +All speakers will be offered a lapel microphone and halo lamp, to help them record quality video (we may choose the items and send you a link with a gift card, so you get the items shipped to you). |
| 105 | +NumFOCUS will prepare a streamlined workflow for you to deliver the raw video, and will send you written instructions. |
| 106 | +In post-processing, we will improve audio, and may add an intro and credits in the end. |
| 107 | +We will then post the video on the JupyterCon YouTube channel. |
| 108 | + |
| 109 | +### Slides |
| 110 | + |
| 111 | +If you will have any portions of your presentation using slides, you can include them in the repository. |
| 112 | +We strongly encourage the use of text-based source for slides, and provide a simple example in the `slides` folder, using Jupytext and Reveal. |
| 113 | +View the example at [https://jupytercon.github.io/tutorial2020/#/](https://jupytercon.github.io/tutorial2020/#/) |
| 114 | + |
| 115 | +### Learner self-assessments |
| 116 | + |
| 117 | +A good tutorial will provide several opportunities for learners to self-assess, and we ask instructors to build these into their tutorial. |
| 118 | +We request that you share the assessments with us privately (i.e., they should not be included in the public repository). |
| 119 | + |
| 120 | +You can craft simple multiple-choice questions to supplement video or written content. In this case, please provide them to us in this markdown format, so we can embed them in the course: |
| 121 | + |
| 122 | +``` |
| 123 | +>>Statement of the question << |
| 124 | +
|
| 125 | +( ) wrong answer |
| 126 | +(x) right answer |
| 127 | +( ) wrong answer |
| 128 | +( ) wrong answer |
| 129 | +
|
| 130 | +[Explanation] |
| 131 | +A short explanation to help learner get it right next time. |
| 132 | +[Explanation] |
| 133 | +``` |
| 134 | + |
| 135 | +Open edX offers several [core problem types](https://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/open-release-ironwood.master/exercises_tools/create_exercises_and_tools.html#core-problem-types), and we can accommodate any of these in your tutorial. |
| 136 | +Please discuss with us by emailing to: |
| 137 | + |
| 138 | + |
| 139 | +### Jupyter auto-graded notebooks |
| 140 | + |
| 141 | +For the tutorial to be most effective, you should include exercises for the learners. |
| 142 | +These exercises, written as Jupyter notebooks, can be auto-graded in the course platform. |
| 143 | +For that, you need to write the exercises in a format that allows using `nbgrader` to create an assignment. |
| 144 | +We have developed an integration in the course platform that allows running `nbgrader` in a container and checking the learner's assignment, at the click of a button. |
| 145 | + |
| 146 | +Each exercise should be divided into incremental steps, and you provide the solution, and a test, usign the `nbgrader` annotations. |
| 147 | +See the [`nbgrader` documentation](https://nbgrader.readthedocs.io/en/stable/user_guide/creating_and_grading_assignments.html#autograded-answer-cells) for detailed instructions on how to insert an "Autograded answer" and an "Autograded test." |
| 148 | + |
| 149 | +Here is an example: |
| 150 | + |
| 151 | + |
| 152 | + |
| 153 | +In the screenshot above, the solution is in cell 3. After we process the notebook, the code between the marks `### BEGIN SOLUTION` and `### END SOLUTION` will be replaced by a note to the learner to "write your code here." |
| 154 | + |
| 155 | +The tests in cell 4 will be hidden from the learner, but will be active and used to check the learners code against the correct answer. |
| 156 | + |
| 157 | +Your assignment notebook should include all the needed `import` statements at the top, and you should include `nose` in the `requirements.txt` (as well as all other dependencies, with their versions). |
| 158 | + |
| 159 | +You will need to [install](https://nbgrader.readthedocs.io/en/stable/user_guide/installation.html) the `nbgrader` Jupyter extension. |
| 160 | +You will only be using the "Create assignment tool," and do not need to follow the later steps to create a student's version of the assignment, as this will be done automatically on the platform. |
| 161 | + |
| 162 | +Open the raw version of your assignment notebook in the environment where you installed `nbgrader`, and you should have the option shown in the screenshot below: |
| 163 | + |
| 164 | +<img src="images/create_assignment.png" width="440" height="250"> |
| 165 | + |
| 166 | +Select "Create Assignment." Every notebook cell should now have a selector to pick the cell type, as shown below: |
| 167 | + |
| 168 | + |
| 169 | + |
| 170 | +Work down the notebook making a selection for every cell: |
| 171 | + |
| 172 | +- "Read-only" for markdown cells with instructions, and cells with `import` commands that you don't want anyone to mess with. |
| 173 | +- "Autograded answer" for code cells that contain the solutions. |
| 174 | +- "Autograded test" for code cells that contain teh tests. |
| 175 | + |
| 176 | +Save the notebook, and this is the version you should send to us. We will create a _private repository_ for all the assignment notebooks. |
| 177 | +Don't include them in the public tutorial repository. |
| 178 | + |
| 179 | +**Pro Tip**: Use a rational naming convention for your tutorial assignment notebooks with a prefix for your tutorial, and a consecutive number for the assignment. |
| 180 | + |
| 181 | +**We strongly encourage tutorials to be complemented by autograded exercises for participants.** |
| 182 | +But we acknowledge that this is hard work for the tutorial speakers. |
| 183 | +Even if your core materials for the tutorial are requested by September 11, we will continue to receive the autograded exercises until the week before the tutorial starts! |
| 184 | + |
| 185 | +The process of building learning sequences on the course platform using your videos and Jupyter notebooks is time consuming. |
| 186 | +Adding an assignment, however, is quick. |
| 187 | +(Remember to add `nose` to your `requirements.txt`.) |
0 commit comments