Expand bullets to text in intro and customization-1

Author: mittler-works

learning-pathways/jupyter-based-teaching.md

@@ -3,7 +3,7 @@ layout: learning-pathway
 title: Jupyter-based teaching
 type: use
 description: |
-  An introduction to Jupyter-based teaching and Jupyter customization.
+  An introduction to Jupyter-based teaching and JupyterLab customization.
 
 editorial_board:
 - mittler-works
@@ -14,27 +14,27 @@ tags: [jupyter, teaching]
 
 pathway:
   - section: "Learn the basics about Jupyter-based teaching"
-    description: "Advantages and limitations of Jupyter-based teaching"
+    description: "An Overview on the Jupyter project components as well as advantages and limitations of Jupyter-based teaching and learning."
     tutorials:
       - topic: teaching
         name: jbt-intro
 
-  - section: "Customize Jupyter to your needs"
-    description: "Adapt Jupyter to your course or workshop specific needs"
+  - section: "Customize JupyterLab to your needs"
+    description: "Adapt JupyterLab to your course or workshop specific needs by installing custom packages, kernels and proxy applications."
     tutorials:
       - topic: teaching
         name: jbt-customization-1
       - topic: teaching
         name: jbt-customization-2
 
   - section: "Featured customizations"
-    description: "Battle-tested and recommended Jupyter extensions for teaching "
+    description: "Battle-tested and recommended JupyterLab extensions for frustration-free teaching and learning."
     tutorials:
       - topic: teaching
         name: jbt-featured
 
-  - section: "Use your customized JupyterLab for Courses"
-    description: "Learn how to teach a course or workshop with your custom JupyterLab"
+  - section: "Productive use of your customized JupyterLab"
+    description: "Learn how to teach a course or workshop, providing you students with your customized JupyterLab."
     tutorials:
       - topic: teaching
         name: jbt-jhaas
@@ -43,4 +43,4 @@ pathway:
 
 ---
 
-You'll learn about the advantages of using Jupyter for teaching and how you can adapt Jupyter to the very specific needs of your course or workshop. As a teacher, you'll learn how to teach a course or workshop using your Jupyter customizations. As a Galaxy admin, you'll learn how to provide your users with a customized Jupyter.
+You'll learn about the advantages of using Jupyter for teaching and how you can adapt JupyterLab to the very specific needs of your courses or workshops. As a teacher, you'll learn how to provide your students with your customized JupyterLab for individual courses or workshops. As a Galaxy admin, you'll learn how to provide your users with a customized JupyterLab each as new interactive tool.

topics/teaching/tutorials/jbt-customization-1/tutorial.md

@@ -1,14 +1,14 @@
 ---
 layout: tutorial_hands_on
 
-title: Basics of Jupyter customization
+title: Basics of JupyterLab customization
 subtopic: practises
 draft: true
 time_estimation: 1h
 questions:
-  - How can I make basic customizations to Jupyter?
+  - How can I make basic customizations to JupyterLab?
 objectives:
-  - An introduction is provided on how to make basic Jupyter customizations, e.g. installing additional plugins.
+  - An introduction is provided on how to make basic JupyterLab customizations, e.g. installing additional plugins.
 key_points:
   - Basic customization costs litte effort and makes it easier for your course participants to get started.
 contributors:
@@ -17,55 +17,87 @@ contributors:
 
 # Prerequisites
 
-* We'll use containerized installation
+One common way to serve JupyterLab is the container-based approach, especially when using a JupyterHub infrastructure provider.
 
-* Examples with docker, as it is easy to install on all major platforms
+This is why this tutorial also follows the container-based approach. As a teacher who wants to customize a container-based JupyterLab you need to install a container runtime as well as some related tools for building container images and more.
 
-# Start your first local Notebook Server with docker
+One of the easier ways to install all the required dependencies is the installation of docker. Docker is available on all major platforms, is very easy to use and has also the advantage, that your produced images will be likely working with any infrastructure provider.
 
-* Show docker stacks
+All examples in this tutorial are therefore developed with docker in mind, but they should of course also work with other container platforms.
 
-* Select an image
+All commands that you should run in a terminal are given with linux in mind. On windows and mac, you might adapt them, e.g. it might not be neccessary (or possible) to use sudo on windows.
 
-* WIP
+## Install docker
 
-```bash
-sudo docker run --rm -it -p 127.0.0.1:8888:8888 quay.io/jupyter/minimal-notebook:2025-06-23
-```
+In order to install docker, please follow the official installation steps. Please read through the whole installation documentation first before starting the installation.
 
-* Will print out a link to `http://localhost:8888/lab?token=<token>`
+- for Linux, I recommend to install docker engine only\
+[https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
 
-## Access your local Notebook Server
+- for Windows, you need docker dekstop - Please use the WSL 2 backend to ensure proper function\
+[https://docs.docker.com/desktop/setup/install/windows-install/](https://docs.docker.com/desktop/setup/install/windows-install/)
 
-* Windows and Mac users will need verification work...
+- for Mac, you also need docker desktop\
+[https://docs.docker.com/desktop/setup/install/mac-install/](https://docs.docker.com/desktop/setup/install/mac-install/)
 
-* WIP
+# Start your first local JupyterLab with docker
 
-## Missing packages
+When you have installed docker successfully, you may now start your first containerized JupyterLab.
+
+In order to run a container you need a container image to start from. The container image defines all the content of the running container. For JupyterLab, there are some prebuild container images for many usecases:
+
+[https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html)
+
+You may select an image that fits closest to your usecase. For this tutorial, we'll use the `jupyter/minimal-notebook` image.
+
+To run this image, open up a terminal and execute:
+
+```bash
+sudo docker run --rm -p 127.0.0.1:8888:8888 quay.io/jupyter/minimal-notebook:2025-06-23
+```
 
-* Install a simple python package
+Let's tear this command apart:
 
-* WIP
+|---|---|
+| sudo | Executes the command with elevated privileges. This is neccassary as docker server is installed as privileged daemon by default. |
+| docker | The docker binary. Allows to talk to the docker daemon. |
+| run | Tells docker to create and start a new container |
+| --rm | Tells docker to remove the container as soon as it's stopped |
+| -p | Tells docker to setup a port forwarding |
+| 127.0.0.1:8888:8888 | The argument for `-p`. A port forwarding on the local interface 127.0.0.1 from port 8888 to the container port 8888 |
+| quay.io/jupyter/minimal-notebook:2025-06-23 | The image to create the container from |
 
-* You are now in a predefined environment. All Packages from mentioned in the docker stacks documentation are there, so you can easily open the `Python 3` Notebook presented on the start page and start working. As you are in a minimal notebook you just do have the python default libraries, but you could run this to get the current weekday:
+## Access your local Notebook Server
+
+The above command will print out a link to `http://localhost:8888/lab?token=<token>`. Copy this link into your browser or just right-click-open the link. You will then see your JupyterLab loading.
+
+When the interface is booted, click on the `Python 3` tile in the Notebook tab to open up a new Notebook. Verify, that everything is working by printing out today's weekday:
 
 ```python
+# Hint: press shift + enter to execute code in Jupyter Notebook
 import datetime
 now = datetime.datetime.now()
 print(now.strftime("%A"))
 ```
 
-* For scientific work you will likely need more than just the default python libraries. Reviewing the docker stacks is helpful and maybe an image like the `scipy-notebook` will have most of the packages you need. But of course these default collections cannot have suitable package selections for the very specific needs of all courses out in the world.
+## Missing packages
+
+You are now in a predefined environment. The packages that are installed are defined by the container image you started, i.e. the `minimal-notebook`. All Packages from this image are available, which are the python default libraries. so you can easily succeed following above steps to print out the weekday, as the used packages are default packages.
+
+For scientific work however, you will likely need more than just the default python libraries. Reviewing the docker stacks is helpful and maybe an image like the `scipy-notebook` will have most of the packages you need. But of course these default collections cannot have perfect fit package selections for the very specific needs of all courses that you could imagine of.
 
-For example, in this minimal setup you might like to have the option to print out text in a fancier way. Luckily, there is a python package for this: `cowsay`. So let's go ahead, try running
+For example, in this minimal setup you might like to have the option to print out the weekday in a fancier way. Luckily, there is a python package for this: `cowsay`. So let's go ahead, try running:
 
 ```python
+# Hint: press shift + enter to execute code in Jupyter Notebook
+import datetime
 from cowsay import cow
-cow('Muuuuh')
-```
 
-As you will see, this fails as cowsay is not available in minimal-notebook.
+now = datetime.datetime.now()
+cow(now.strftime("%A"))
+```
 
+As you will see, this fails with a `ModuleNotFoundError` as cowsay is not available in minimal-notebook.
 
 # Build your first custom Image
 

topics/teaching/tutorials/jbt-featured/tutorial.md

@@ -83,6 +83,8 @@ It should pull the repo and opens the example automatically. You should be able
 
 https://github.com/jupyter/nbgrader
 
+More: https://nbgrader.readthedocs.io/en/stable/
+
 ## Install
 
 ## Configuration

topics/teaching/tutorials/jbt-intro/tutorial.md

@@ -1,12 +1,12 @@
 ---
 layout: tutorial_hands_on
 
-title: An introduction to Jupyter based teaching
-subtopic: practises
+title: An introduction to Jupyter-based teaching
+subtopic: introduction
 draft: true
 time_estimation: 15m
 questions:
-  - What are the general advantages and limitations of Jupyter based teaching?
+  - What are the general advantages and limitations of Jupyter-based teaching?
 objectives:
   - An overview is provided to familiarize teachers with the advantages and limitations of Jupyter-based teaching.
 key_points:
@@ -15,34 +15,43 @@ contributors:
   - mittler-works
 ---
 
-* Central Platform for interactive teaching
+Jupyter Notebooks are a promising way to provide participants of a course or workshop with an easy-to-use, webbased, interactive and reproducible environment to learn and work with.
 
-* All in one place, Code, Text, Math, Plots and more
+Jupyter Notebooks makes it possible to Code in various programming languages, writing documentation and other text, doing math, printing plots and much more in one single environment. All relevant resources are ready to be used.
 
-* No installation required
+Jupyter Notebooks can be run on an individual machine as well as centrally managed by a JupyterHub server. If provided via JupyterHub, the webbased access truly allows participants to bring their own device, as their devices only need to satisfy common web standards and do not need to satisfy the requirements of the software running inside the notebook, as this will be run on the server. No installation on the participants device required.
 
-* Low entry access
+This allows for an low-level access especially for beginner courses or workshops.
 
-* Easy scalable
+As a teacher you may provide a predefined learning environment, i.e. a predefined software stack, data, configuration and more. This allows you to cover all the necessary requirements in advance, so your participants do not have to carry out further setup steps during the course, as these tend to be frustrating in many szenarios.
 
-* Custom Courses in predefined Environments
+If you use an infrastructure provider for your course, you only have to deal with your JupyterLab customizations in order to adapt JupyterLab to your course. The deployment of these JupyterLabs in order to provide them to your participants is the infrastructure providers' job. With this in mind it makes little difference if you plan your JupyterLab for three or three hundred participants, as it is horizontally scalable.
 
 # Jupyter Terminology
 
-In the context of Jupyter, there are some components with similar terminology involved. It is important to know how to keep them apart, which is why this tutorial begins with a list of common Jupyter wording.
+To get started, we have to elaborate on some terminology. Especially the term `Jupyter Notebook` is heavily overloaded and may be used in many szanarios while having very different meanings. Over all, in the context of Jupyter, there are some components with similar terminology involved. It is important to know how to keep them apart.
+
+> <question-title>Which Jupyter-related terms do you now?</question-title>
+> 
+> Just take a moment and think about what Jupyter-related terms you have already heard about. For each term that comes to your mind, can you explain how it fits into the Jupyter landscape?
+{: .question}
+
+
+Let's start this tutorial with a list of a few very common and important Jupyter terms.
 
 ### Jupyter
-is the name of the umbrella open source project that provides Jupyter Notebook, JupyterLab, JupyterHub and many more projects.
+Jupyter itself is the name of the umbrella open source project that provides software components like Jupyter Notebook, JupyterLab, JupyterHub and many more projects. Jupyter itself is not a software nor a file format.
 
 ### Jupyter Notebook
-is a computer program that serves a webbased interactive tool for writing, documenting, and sharing code. Please note, that the `.ipnb` document itself is often reffered to as the Jupyter Notebook. Please always mind the context to distinguish between the Jupyter Notebook program and the Jupyter Notebook document.
+Jupyter Notebook is a computer program that serves a webbased interactive tool for writing, documenting, and sharing code. It is commonly used on a local machine. Note, this term is heavily overloaded and it is common that the `.ipnb` files themselves are reffered to as Jupyter Notebooks too.
+
+Please always mind the context to distinguish between the Jupyter Notebook program and the Jupyter Notebook file.
 
 ### JupyterLab
-is a computer program that serves an extensible webbased environment for interactive coding, that combines Jupyter Notebook with other components like text editors, terminals, kernels, plots and more.
+JupyterLab is a computer program that serves an extensible webbased environment for interactive coding, that combines Jupyter Notebook with other components like text editors, terminals, kernels, plots and more.
 
 ### JupyterHub
-is a centralized organizational platform for JupyterLab on a server. It allows to provide many users with JupyterLab instances and handles authentication and authorization.
-
+JupyterHub is a centralized organizational platform for managing JupyterLab instances on a server. It allows to provide many users with JupyterLab instances and handles authentication and authorization.
 
 # Advantages for teaching