One of the things I try to do in many of my demo Jupyter notebooks is explain what’s going on so that readers who aren’t (yet) Python programmers can hopefully form some understanding of what the code is doing.
This Simple demo notebook originally started out as a really quick notebook containing little more than code blocks that showed how to download and review some WEC (World Endurance Championsip) laptime data; but then I started iterating it, adding in more explanatory code steps, prefaced by markdown text that tried to explain what the following line of code was going to do.
One of the ongoing debates we have in our TM351 Data Management and Analysis course is whether students need to know how to programme in Python to do the course, i.e. whether the module should have a Python programming course prerequisite, or at least a programming skill prerequisite (I argue in favour of no prerequisites).
Certainly, explaining each step of the code adds more words and makes each notebook a much longer read; but a lot of effective distance teaching does involve repetition and rehearsal. The line by line, “explain what you’re want to do and how you’re going to do it; do it’ preview the output” approach also “unpacks” each line of code in a problem solving / goal directed context (“I want to do this, which requires that I have previously done that“).