Five guiding principles to make Jupyter Notebooks educational and reusable
Julia Wagemann, Simone Mantovani, Sabrina H. Szeto
Jupyter notebooks are a popular choice for training and teaching data-intensive science, such as training users of large volumes of Earth Observation data. Computational notebooks, including Jupyter, are in particular valued for facilitating reproducibility and collaboration. However, quantitative analyses and empirical research have identified unique challenges when it comes to using them. Critics claim that notebooks foster bad coding practices due to the possibility of an out-of-order execution of cells, that only a small percentage of notebooks hosted on Github are in fact reproducible and that annotations are not evenly distributed and do not reach the objective of well-described computational narratives.
These findings are the motivation to develop and share best practices to make Jupyter notebooks more educational and reusable. During the development of a Jupyter-based training course on Earth Observation data (Learning Tool for Python (LTPy)), we defined and applied five guiding principles from different fields (mainly scientific computing and Jupyter notebook research) to make these notebooks more educational and reusable.
The Jupyter notebooks developed (i) follow the literate programming paradigm by a text/code ratio of 3, (ii) use instructional design elements to improve navigation and user experience, (iii) modularize functions to follow best practices for scientific computing, (iv) leverage the wider Jupyter ecosystem to make content accessible, and (v) aim for being reproducible.
In this talk, we will share with you five guiding principles to make Jupyter notebooks educational and reusable and for each principle we share a practical example of how it can be applied and implemented. The guiding principles have also been published in the Journal of Remote Sensing.