Materials

Best practices and resources for preparing teaching materials.

Repositories

	Course	Materials Repository	Exams Repository
BDA	Big Data and Analytics	repository	repository
ITSecM	IT Security Management	repository	repository
IDW	Introduction to Digital Work	repository	repository
OSP	Open Source Project	repository	—
LRSem	Literature Review Seminar	repository	—
Theses	Theses	repository	—

General setup

We use Quarto for our teaching materials.

Important

Do not create quarto brand extension or use the revealjs seminar plugin (complexity).

Principles

Dates, rooms, and links should be in one place to prevent inconsistent information.
VC links never point to a specific course but to a search in VC (e.g., for the project).
Teaching contents are licensed under the CC-BY license per default.
Design contents in such a way that students can learn them (after the session, pdf, making comments)
Add dynamic illustrations only as an extra (link them in the offline version)

Important

Each sentence should be in a new line (to ensure that the git diff is readable). To create a paragraph, add an empty line. This makes the history more readable and merging easier (see semantic line breaks).

A teaching repository contains

Overview of related courses in the REAMDE.md file (see other courses here).
PDFs should be generated through make pdfs (a make -> quarto render -> decktape chain, as in bda).
A syllabus (example)
Detailed teaching notes allow teaching assistants to replicate it quickly.
Links related to continuous improvement: feedback, evaluations, improvement.
Add branch protection rule for main: restrict deletions and block force pushes
Each course should have a separate repository and page.
Options to provide feedback should be linked on the first page.
Optional: surveys to collect feedback for individual sessions (Google Forms?)
Optional: ask students how they learn (PDF, …) whether they use a knowledge management system (which one), and adapt accordingly

Publishing to GitHub pages

For quarto publish gh-pages : install quarto locally (otherwise, the ssh and git setup in the docker container requires detailed configuration).

Adding extensions

docker compose run --rm quarto quarto add gadenbuie/countdown/quarto
docker compose run --rm quarto quarto add martinomagnifico/quarto-simplemenu

Slides

Template is available here (see tutorial)

Slides are in reveal-js.
HTML and PDF versions are automatically generated (e.g., GitHub actions).
Learning objectives should be on all slides (verifiable outcomes).
Use markers for tasks/questions (see example)

Quarto extensions for slides:

simplemenu
pointer
custom callouts
downloadthis
code animations
countdown timer (link exercise sheets on slides)
flashcards for quick questions with solutions displayed on pressing q

Slide template

:::{.callout-note}
Note that there are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Your content here… [^1]

[^1]: A url and further information.


@CastonguayWagnerMotulskyEtAl2023 is useful.

<!-- _class: centered -->
Centered text...

TODO: Mermaid diagrams

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

Feedback

Limesurvey
Rustpad for anonymous feedback/suggestions (contents are deleted after 1 day of inactivity)

Embedding Google Forms (anonymous responses possible):

<style>
blockquote {
    border-top: 0.1em;
    font-size: 60%;
    margin-top: auto;
}
</style>

<iframe src="https://docs.google.com/forms/d/e/1FAIpQLSeACViOkyuuG3Bvz4Dhq1yA-Fm8WTPiRst5D_IxK3UuRyFzjg/viewform?embedded=true" width="100%" height="90%" frameborder="" marginheight="0" marginwidth="0">Wird geladen…</iframe>

> Open [responses](https://docs.google.com/forms/d/1Wa_MNL3zClW7j-1NPm31PIP7pXs7QqLnZPi4oefA_gA/edit#responses){target=_blank}

Typography defaults:

  --font-family: "Source Sans Pro", sans-serif;

Adding headings to the navigation

## Heading {data-menu-title="I. Overview"}

### Will not be in the navigation

Timer

quarto add gadenbuie/countdown/quarto

{{< countdown minutes=5 seconds=32 top=10 left=0 >}}

Code annotation

See link:

library(tidyverse)
library(palmerpenguins)
1penguins |>
2  mutate(
    bill_ratio = bill_depth_mm / bill_length_mm,
    bill_area  = bill_depth_mm * bill_length_mm
  )

1: Take penguins, and then,
2: add new columns for the bill ratio and bill area.

Icons

Based on Bootstrap

{{icon="mortarboard-fill"}}

Shortcuts:

g : goto slide
b
d

Convert PowerPoint to quarto:

pptx2md "slides.pptx" --output "slides_with_notes.qmd" --enable-slides --qmd --image-dir "images"

Notebooks

We use Jupyter notebooks for exercises. The benefits of Jupyter notebooks are summarized by Vial & Negoita (2018):

No separation between code and pedagogical materials, no need to switch attention between materials for students.
Interactive Python: re-running parts of the code (instead of the entire program) with variables and objects staying in memory.
Option to include short problems for students.

Jupyter notebooks should be delivered through GitHub Codespaces to avoid individual setup problems (see Malan, 2024).

Notebook template

TODO

<!--
Comments can be used to add further explanations or links to references/resources
-->

Resources for notebook design

Teaching notes

Teaching notes are shared and updated regularly.

Teaching notes template

---
title: "Session X: XXX"
---

### Week 1: Topics (Teaching notes)

| Time (min) | Duration  | Topic                                                                          | Additional materials                           |
|------------|-----------|--------------------------------------------------------------------------------|------------------------------------------------|
| 0-10       | 10        | [Intro and instructor background](#intro)                                      |                                                |
| 10-25      | 15        | [What you will learn](#what-you-will-learn)                                    |                                                |
| 50-80      | 30        | [Orientation in Open Source projects](#orientation-in-open-source-projects)    | Group task, discussing solutions afterwards    |
| 80-90      | 10        | [Next steps](#next-steps)                                                      |                                                |

::: objective
In this session, our goal is to .... (competencies)
:::

Summary of last session.

### Intro and instructor <a id="intro"></a>

- Contents (e.g., photo of the board writing)
- Highlight areas that can be shortened (optional)
- Additional challenges and tasks for students
- Typical questions raised (common errors)

Summarize lessons learned.

::: callout-note
**Page breaks for PDFs/print**

&lt;div class=&quot;page-break&quot;&gt;&lt;/div&gt;
:::

Native page break:

{{< pagebreak >}}

Resources

Instructor guide
awesome quarto
Slidecrafting: Making beautiful slides with reveal.js and Quarto
revealjs editor (slides.com): ai prompts limited (generating many slides, or changing text fields) - cannot do animations with it. limited import/export (for quarto/revealjs) - only complex/full htm.

Terminal animations (asciinema)

Installation

pip install asciinema
git clone https://github.com/asciinema/agg
cd agg
docker build -t agg .

Recording and conversion

asciinema rec demo.cast
# code ...
# ctrl+d to quit
# convert:
docker run --rm -it -u $(id -u):$(id -g) -v $PWD:/data agg demo.cast demo.gif

Possible extensions

Workflows (quality checks)
Setup of exercises
Quartz (obsidian) and infos on how to export notes (obsidian/notion/word)

Quarto extensions

https://github.com/jmbuhr/quarto-qrcode
https://github.com/fradav/quarto-revealjs-animate
https://github.com/ofkoru/quarto-animate-graph
https://github.com/parmsam/quarto-excalidraw
https://github.com/gadenbuie/quarto-now
https://github.com/parmsam/quarto-subtitles
https://github.com/EmilHvitfeldt/quarto-revealjs-highlightword
https://github.com/produnis/quarto-cheatsheet
https://github.com/ofkoru/quarto-leader-line
https://github.com/parmsam/quarto-quizdown (interactive - incompatible with PDF export)
https://github.com/shafayetShafee/interactive-sql
https://github.com/peter-gy/quarto-gradio
https://quarto.thecoatlessprofessor.com/pyodide/
https://github.com/coatless-quarto/pyodide
https://github.com/quarto-ext/shinylive
https://github.com/coatless/quarto-webr?tab=readme-ov-file
https://github.com/EmilHvitfeldt/quarto-snow
https://github.com/quarto-ext/fontawesome
https://parmsam.github.io/quarto-github-corner/

References

Malan, D. J. (2024). Containerizing CS50: Standardizing students’ programming environments. In Proceedings of the 2024 on innovation and technology in computer science education v. 1 (pp. 534–540). https://doi.org/10.1145/3649217.3653567

Vial, G., & Negoita, B. (2018). Teaching programming to non-programmers: The case of python and jupyter notebooks. International Conference on Information Systems. https://aisel.aisnet.org/icis2018/education/Presentations/1/

--- title: "Materials" bibliography: ../assets/complementary-references.bib csl: ../assets/apa.csl --- Best practices and resources for preparing teaching materials. ## Repositories | | Course | Materials Repository | Exams Repository | |--------|------------------------------|-----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| | BDA | Big Data and Analytics | [repository](https://github.com/fs-ise/big-data-analytics){target=_blank} | [repository](https://github.com/fs-ise/big-data-analytics-exams){target=_blank} | | ITSecM | IT Security Management | [repository](https://github.com/fs-ise/it-security-management){target=_blank} | [repository](https://github.com/fs-ise/it-security-management-exams){target=_blank} | | IDW | Introduction to Digital Work | [repository](https://github.com/fs-ise/digital-work-lecture){target=_blank} | [repository](https://github.com/fs-ise/digital-work-lecture-exam){target=_blank} | | OSP | Open Source Project | [repository](https://github.com/fs-ise/open-source-project){target=_blank} | — | | LRSem | Literature Review Seminar | [repository](https://github.com/fs-ise/literature-review-seminar){target=_blank} | — | | Theses | Theses | [repository](https://github.com/fs-ise/theses){target=_blank} | — | ## General setup We use [Quarto](https://quarto.org/){target=_blank} for our teaching materials. ::: callout-important Do not create quarto brand extension or use the revealjs seminar plugin (complexity). ::: Principles - Dates, rooms, and links should be in one place to prevent inconsistent information. - VC links never point to a specific course but to a search in VC (e.g., for the [project](https://vc.uni-bamberg.de/course/search.php?search=Digital-Work-Projekt-B){target=_blank}). - Teaching contents are licensed under the [CC-BY license](https://creativecommons.org/licenses/by/4.0/deed.en){target=_blank} per default. - Design contents in such a way that students can learn them (after the session, pdf, making comments) - Add dynamic illustrations only as an extra (link them in the offline version) ::: {.callout-important} Each sentence should be in a new line (to ensure that the git diff is readable). To create a paragraph, add an empty line. This makes the history more readable and merging easier (see [semantic line breaks](https://sembr.org/){target=_blank}). ::: A teaching repository contains - Overview of related courses in the REAMDE.md file (see other courses [here](platforms_degree_programs_courses.html)). - PDFs should be generated through `make pdfs` (a `make` -> `quarto render` -> `decktape` chain, as in [bda](https://github.com/fs-ise/big-data-analytics){target=_blank}). - A syllabus ([example](https://fs-ise.github.io/open-source-project/docs/syllabus.html){target=_blank}) - Detailed teaching notes allow teaching assistants to replicate it quickly. - Links related to continuous improvement: **feedback**, **evaluations**, **improvement**. - Add branch protection rule for `main`: restrict deletions and block force pushes - Each course should have a separate repository and page. - Options to provide feedback should be linked on the first page. - Optional: surveys to collect feedback for individual sessions (Google Forms?) - Optional: ask students how they learn (PDF, ...) whether they use a knowledge management system (which one), and adapt accordingly ### Publishing to GitHub pages For `quarto publish gh-pages` : install quarto locally (otherwise, the ssh and git setup in the docker container requires detailed configuration). ### Adding extensions ```sh docker compose run --rm quarto quarto add gadenbuie/countdown/quarto docker compose run --rm quarto quarto add martinomagnifico/quarto-simplemenu ``` ## Slides Template is available [here](https://github.com/fs-ise/fs-ise-presentation){target=_blank} (see [tutorial](https://www.jtrive.com/posts/creating-gh-pages-blog-with-quarto/creating-gh-pages-blog-with-quarto.html){target=_blank}) - Slides are in reveal-js. - HTML and PDF versions are automatically generated (e.g., GitHub actions). - Learning objectives should be on all slides (verifiable outcomes). - Use markers for tasks/questions (see [example](https://fs-ise.github.io/literature-review-seminar/output/01-goals.html#4){target=_blank}) Quarto extensions for slides: - [simplemenu](https://github.com/martinomagnifico/quarto-simplemenu){target=_blank} - [pointer](https://github.com/quarto-ext/pointer){target=_blank} - [custom callouts](https://quarto.thecoatlessprofessor.com/custom-callout/){target=_blank} - [downloadthis](https://github.com/shafayetShafee/downloadthis){target=_blank} - [code animations](https://quarto.org/docs/presentations/revealjs/advanced.html#code-animations){target=_blank} - [countdown timer](https://github.com/gadenbuie/countdown){target=_blank} (link exercise sheets on slides) - [flashcards for quick questions with solutions displayed on pressing `q`](https://github.com/parmsam/quarto-webcam){target=_blank} ::: {.callout-note title="Slide template" collapse=true} ```Markdown :::{.callout-note} Note that there are five types of callouts, including: `note`, `tip`, `warning`, `caution`, and `important`. ::: Your content here… [^1] [^1]: A url and further information. @CastonguayWagnerMotulskyEtAl2023 is useful.  Centered text... ``` TODO: Mermaid diagrams ```{mermaid} flowchart LR A[Hard edge] --> B(Round edge) B --> C{Decision} C --> D[Result one] C --> E[Result two] ``` **Feedback** - Limesurvey - [Rustpad](https://rustpad.io/#GCUiny){target=_blank} for anonymous feedback/suggestions (contents are deleted after 1 day of inactivity) Embedding Google Forms (anonymous responses possible): ```html <style> blockquote { border-top: 0.1em; font-size: 60%; margin-top: auto; } </style> <iframe src="https://docs.google.com/forms/d/e/1FAIpQLSeACViOkyuuG3Bvz4Dhq1yA-Fm8WTPiRst5D_IxK3UuRyFzjg/viewform?embedded=true" width="100%" height="90%" frameborder="" marginheight="0" marginwidth="0">Wird geladen…</iframe> > Open [responses](https://docs.google.com/forms/d/1Wa_MNL3zClW7j-1NPm31PIP7pXs7QqLnZPi4oefA_gA/edit#responses){target=_blank} ``` Typography defaults: ```css --font-family: "Source Sans Pro", sans-serif; ``` Adding headings to the navigation ```Markdown ## Heading {data-menu-title="I. Overview"} ### Will not be in the navigation ``` **Timer** quarto add gadenbuie/countdown/quarto ```Markdown {{< countdown minutes=5 seconds=32 top=10 left=0 >}} ``` **Code annotation** See [link](https://quarto.org/docs/authoring/code-annotation.html){target=_blank}: ```r library(tidyverse) library(palmerpenguins) penguins |> # <1> mutate( # <2> bill_ratio = bill_depth_mm / bill_length_mm, # <2> bill_area = bill_depth_mm * bill_length_mm # <2> ) # <2> ``` 1. Take `penguins`, and then, 2. add new columns for the bill ratio and bill area. **Icons** Based on [Bootstrap](https://icons.getbootstrap.com/){target=_blank} ```Markdown {{icon="mortarboard-fill"}} ``` ::: Shortcuts: - g : goto slide - b - d Convert PowerPoint to quarto: ```sh pptx2md "slides.pptx" --output "slides_with_notes.qmd" --enable-slides --qmd --image-dir "images" ``` ## Notebooks We use Jupyter notebooks for exercises. The benefits of Jupyter notebooks are summarized by @VialNegoita2018: - No separation between code and pedagogical materials, no need to switch attention between materials for students. - Interactive Python: re-running parts of the code (instead of the entire program) with variables and objects staying in memory. - Option to include short problems for students. Jupyter notebooks should be delivered through GitHub Codespaces to avoid individual setup problems [see @Malan2024]. ::: {.callout-note title="Notebook template" collapse=true} ```Markdown TODO  ``` ::: ::: {.callout-note title="Resources for notebook design" collapse=true} - [CodeRefinery on Jupyter Notebooks](https://coderefinery.github.io/jupyter/){target=_blank} - [Exercise worksheets with Jupyter notebooks](https://www.epfl.ch/education/educational-initiatives/jupyter-notebooks-for-education/teaching-and-learning-with-jupyter-notebooks/exercise-worksheets-with-jupyter-notebooks/){target=_blank} - [Example 1](https://github.com/yaozeliang/Python-100-exercises-notebook){target=_blank} - [Example 2](https://github.com/jerry-git/learn-python3){target=_blank} - [Live code running](https://r-wasm.github.io/quarto-live/){target=_blank} - [assign](https://github.com/coatless-quarto/assign){target=_blank} - [downloadthis](https://github.com/shafayetShafee/downloadthis){target=_blank} ::: ## Teaching notes - Teaching notes are shared and updated regularly. ::: {.callout-note title="Teaching notes template" collapse=true} ```Markdown --- title: "Session X: XXX" --- ### Week 1: Topics (Teaching notes) | Time (min) | Duration | Topic | Additional materials | |------------|-----------|--------------------------------------------------------------------------------|------------------------------------------------| | 0-10 | 10 | [Intro and instructor background](#intro) | | | 10-25 | 15 | [What you will learn](#what-you-will-learn) | | | 50-80 | 30 | [Orientation in Open Source projects](#orientation-in-open-source-projects) | Group task, discussing solutions afterwards | | 80-90 | 10 | [Next steps](#next-steps) | | ::: objective In this session, our goal is to .... (competencies) ::: Summary of last session. ### Intro and instructor <a id="intro"></a> - Contents (e.g., photo of the board writing) - Highlight areas that can be shortened (optional) - Additional challenges and tasks for students - Typical questions raised (common errors) Summarize lessons learned. ::: callout-note **Page breaks for PDFs/print** <div class="page-break"></div> ::: ``` Native page break: ```markdown {{{< pagebreak >}}} ``` ::: ## Resources - [Instructor guide](https://coderefinery.github.io/documentation/guide/){target=_blank} - [awesome quarto](https://github.com/mcanouil/awesome-quarto){target=_blank} - [Slidecrafting: Making beautiful slides with reveal.js and Quarto](https://slidecrafting-book.com/){target=_blank} - revealjs editor (slides.com): ai prompts limited (generating many slides, or changing text fields) - cannot do animations with it. limited import/export (for quarto/revealjs) - only complex/full htm. ::: {.callout-note title="Terminal animations (asciinema)" collapse=true} Installation ```sh pip install asciinema git clone https://github.com/asciinema/agg cd agg docker build -t agg . ``` Recording and conversion ```sh asciinema rec demo.cast # code ... # ctrl+d to quit # convert: docker run --rm -it -u $(id -u):$(id -g) -v $PWD:/data agg demo.cast demo.gif ``` ::: **Possible extensions** - Workflows (quality checks) - Setup of exercises - Quartz (obsidian) and infos on how to export notes (obsidian/notion/word) ::: {.callout-note title="Quarto extensions" collapse=true} - https://github.com/jmbuhr/quarto-qrcode - https://github.com/fradav/quarto-revealjs-animate - https://github.com/ofkoru/quarto-animate-graph - https://github.com/parmsam/quarto-excalidraw - https://github.com/gadenbuie/quarto-now - https://github.com/parmsam/quarto-subtitles - https://github.com/EmilHvitfeldt/quarto-revealjs-highlightword - https://github.com/produnis/quarto-cheatsheet - https://github.com/ofkoru/quarto-leader-line - https://github.com/parmsam/quarto-quizdown (interactive - incompatible with PDF export) - https://github.com/shafayetShafee/interactive-sql - https://github.com/peter-gy/quarto-gradio - https://quarto.thecoatlessprofessor.com/pyodide/ - https://github.com/coatless-quarto/pyodide - https://github.com/quarto-ext/shinylive - https://github.com/coatless/quarto-webr?tab=readme-ov-file - https://github.com/EmilHvitfeldt/quarto-snow - https://github.com/quarto-ext/fontawesome - https://parmsam.github.io/quarto-github-corner/ :::