title: Bereitstellen neuer Tutorials für den Schulstick

Schulstick Tutorials

Der Schulstick ist eine freie Lern-, Spiel- und Arbeitsplattform für Lernende jeden Alters. Für unterschiedliche Zielgruppen existieren verschiedene Varianten. Im Weiteren geht es um die Variante Schulstick. Alle weiteren Varianten enthalten alles, was der Schulstick enthält.

Ein besonderer Wert des Schulsticks besteht darin, eine einheitliche Plattform für eine Vielzahl speziell angepasster und getesteter Tutorials zu bieten. Ziel ist es Nutzern (Schülern, Lehrkräften und Autodidakten) einen besonders zuverlässigen, niedrigschwelligen, frustfreien und effizienten Einstieg in neue Themen, Technologien und Softwarelösungen zu ermöglichen.

Lerninhalte für den Stick sind freies Wissen und werden durch eine Community gemeinsam erstellt und gepflegt. In der FAQ werden Fragen beantwortet, wie alle, die das Projekt unterstützen wollen, unkompliziert mithelfen können.

Die folgende Anleitung erklärt alle nötigen Schritte um:

1. Zu verstehen wie die Tutorials aufgebaut sind
2. Ein neues Tutorial anzulegen
3. Tutorials im Lernportal auf dem Schulstick zu testen
4. Inhalte (z.B. Lektionen oder ganze Kurse) zu veröffentlichen

Aufbau von Tutorials

Wir sammeln und pflegen Tutorials in einem gemeinsamen Verzeichnis auf Github.

Keine Angst, für keinen der Schritte aus dieser Anleitung ist Wissen über Git notwendig. Um eine einfache Anleitung zu erstellen, müssen nur drei Dateien erstellt und uns zugesendet werden.

Hier ein einfaches Beispiel eines Tutorials:

Der Ordner enthält die nötigen 3 Dateien:

• intro.md
• metadata.yml
• preview.png

Die folgenden Abschnitte erklären für jede der Dateien, was sie beinhalten, wie sie erstellt und getestet werden können.

Für fortgeschrittene Anwendungsfälle kann ein Tutorial noch weitere Dateien enthalten. Diese werden im folgenden mit erklärt; da die Dateien aber nicht zwingend benötigt werden, können die zugehörigen Kapitel aber für das Erstellen des ersten Tutorials gerne übersprungen werden.

intro.md

Diese Datei beinhaltet die eigentlichen Inhalte.

Die Datei ist in der Auszeichnungssprache Markdown geschrieben.

LiaScript

metadata.yml

Die in Markdown/LiaScript geschriebene Datei (intro.md) ist ausreichend um eine Anleitung unabhängig vom Schulscript zu schreiben.

lesson.yml enthält alle Metadaten welche vom Schulstick-Portal benötigt werden, um zusätzliche Funktionen zu ermöglichen. Sie wird künftig optional sein.

Wir werden in einem späteren Abschnitt beschreiben, wie die Datei einfach erstellt/angepasst/getestet werden kann und welche Werte in ihr erlaubt sind.

Zunächst ist es für uns wichtig zu wissen, dass die Datei metadata.yml, welche für jedes Tutorial vorhanden sein muss, folgende beiden Zeilen enthält:

markdownFile: "intro.md"
previewImage: "preview.png"

Der Wert hinter dem Schlüsselwort markdownFile benennt die Markdown/LiaScript-Datei, welche den Anfang des Tutorials beinhaltet.

preview.png

Das Schulstick-Portal zeigt in der Liste der vorhandenen Tutorials jeweils ein Vorschaubild. In unserem Fall preview.png. Die Datei muss unter dem Name existieren, wie sie in metadata.yml unter dem Schlüsselwort previewImage benannt wurde.

Bitte suche für dein Tutorial ein geeignetes Bild heraus oder erzeuge ein eigenes. Wenn ein vorhandenes Bild verwendet wird, bitte beachte, dass es unter einer freien Lizenz steht.

optionale Erweiterungen

Die bisher betrachteten 3 Dateien sind ausreichend um ein minimales Tutorial zu erstellen.

Wenn du direkt beginnen magst, kannst du gerne direkt im Kapitel weiterlesen.

Der Vollständigkeit halber — falls du später nachschauen magst oder wenn es dich gleich interessiert — im folgenden noch die optionalen Konfigurationsoptionen für das Schulstick-Portal…

Aufteilung und Verlinkung von Tutorials und Lektionen

Wenn dein Tutorial sehr lang wird, kann es nützlich sein, das Tutorial in separate Dateien für unterschiedliche Lektionen zu unterteilen.

Die Lektionen eines Tutorials können untereinander verlinkt werden. Als Linkziel wird dafür die relative Pfadangebe der verlinkten .md-Datei angegeben.

Skripte

Motivation

Das Portal soll es ermöglichen, dass Tutorials als eng miteinander verknüpfte Kombination aus Anleitung und Anwendung bzw. Anwendungsumgebung interagieren können. Für viele Lerninhalte wird es ausreichen, wenn eine (oder mehrere) GUI-Anwendungen am Anfang einer Lektion geöffnet werden.

In einigen Fällen ist jedoch gewünscht, dem Ersteller des Tutorials mehr Kontrolle über erforderliche Umgebungen zu ermöglichen, als ein bereits vorinstalliertes Softwarepaket in seiner Originalversion zu starten. Manche Anwendungen müssen mit bestimmten Plugins, Konfigurationsdateien, sonstigen Argumenten oder in einer bestimmten Version vorhanden sein. Ein großer Mehrwert des Bereitstellens der Tutorials auf dem Schulstick ist die Möglichkeit, dass der Ersteller der Lerninhalte genau die später vom Nutzer verwendete Version der Software testen und für die entsprechende Version korrekte Screenshots einbinden kann. Wenn Software über die Zeit aktualisiert wird, kann nicht vom Kernteam des Schulsticks erwartet werden, dass immer alle Tutorials im Detail überprüft werden, ob in den Anleitungen Anpassungen nötig geworden sind. Daher ist es wünschenswert, das Wissen der Inhalteersteller zu nutzen, um zu gewährleisten, dass Anwendungen und Anleitungen aufeinander abgestimmt sind.

Hooks

Entwickelnde von Tutorials, die sich etwas besser mit Linux auskennen, können im Ordner ihrer Lektionen shell-Skripte ablegen, und bekommen folgende Möglichkeiten sich ins System „einzuhaken“:

• ./scripts/run.sh
• ./scripts/run_test.sh
• ./scripts/install.sh
• ./scripts/install_test.sh

run.sh

Wenn die Datei ./scripts/run.sh im Lektionsordner existiert, wird anstatt der in metadata.yml benannten Anwendung das Shell-Skript ausgeführt.

Auf diese Weise bekommt der Ersteller des Tutorials die Möglichkeit, GUI-Anwendungen und Komandozeilen-Umgebungen nach dem Bedürfnis des Tutorials zu starten. Das Skript läuft mit den Berechtigungen des Portal-Nutzers.

Mittels run.sh kann bei Bedarf z.B. der LiaScript-CodeRunner gestartet werden, welcher Code aus interaktiven LiaScript-Kursen evaluieren kann.

run_test.sh

Wenn die Datei ./scripts/run_test.sh existiert, wird diese beim Lektionsstart immer vor der eigentlichen Anwendung (bzw. run.sh) ausgeführt.

Dieses Skript hat den Zweck unmittelbar vor der Laufzeit zu testen, ob alle Erwartungen des Tutorial-Erstellers erfüllt sind. Beispielsweise kann überprüft werden, ob eine Anwendung in der erwarteten Version installiert ist oder ob Systemeinstellungen und auf dem System vorhandene Ressourcen den Ansprüchen genügen.

Wenn das Skript vorhanden ist, muss es sich wie folgt verhalten:

• Das Skript sollte möglichst zügig terminieren
• Der Exit-Code muss bei Erfolg 0 sein, in diesem Fall wird die Anwendung wie vom Nutzer erwartet gestartet.
• Der Exit-Code darf bei erkannten Problemen die Exit-Codes gemäß dem Standart von Nagios-Plugins zurückgeben.
• Ausgabe an stdout muss sich auf knappe, für die Zielgruppe des Tutorials verständliche Warnungen/Fehlermeldungen beschränken. Das Portal kann diese in einem Dialog an den Nutzer durchreichen.
• Ausgaben an stderr darf (beliebige) Debug-Ausgaben beinhalten. Sie werden dem Endnutzer vom Portal nicht durchgereicht.

install.sh

Während die ersten beiden Skripte zur Laufzeit und mit Benutzerprivilegien liefen, ermöglichen install.sh und install_test.sh ähnliche Funktionalität zum Zeitpunkt der Installation durch einen Nutzer mit Administratorrechten.

install.sh kann bei Bedarf Konfigurationsdateien (wie z.B. udev-Regeln) erstellen oder den Nutzer zu einer weiteren Benutzergruppe hinzufügen.

install_test.sh

Im Vergleich zu install.sh sollte install_test.sh nie die Systemkonfiguration manipulieren, sondern ausschließlich zur Installtionszeit testen.

Ausgabe und Return-Codes sollten sich genau wie bei run_test.sh verhalten.

Sicherheitsüberlegungen

Diese Skripte führen vom Tutorialersteller generierten und von der Community gereviewten Code auf dem System des Nutzers aus. Skripte und ihre Änderungen sollten daher von der Community genauso gründlich wie der Schulstick selbst überprüft werden. Für Tutorials mit Skripten wird ein Review-Prozess empfohlen, bei dem vor dem Mergen, mindestens ein Approval eines anderen vertrauten Nutzers erteilt wurde.

run.sh und run_test.sh laufen mit Nutzerprivilegien. Das Schadenspotential wird ähnlich eingeschätzt, wie jenes, welches Ersteller von Tutorials mittels bösartigen Inhalten in ihren Anleitungen verursachen können. Das erlauben wohl definierter und überprüfter Hooks kann einen Sicherheitsvorteil bieten, wenn sie einen Beitrag leisten, dass Tutorials höheren Standarts genügen müssen. Der Mechanismus der Hooks sollte genutzt werden, um dubiose Installationsanleitungen in den Tutorials konsequent zu verbieten. Dies betrifft insbesondere das Laden von Code aus Drittquellen.

install.sh und install_test.sh stellen einen Sicherheitskompromiss zu gunsten der Umsetzbarkeit, Wartbarkeit und Qualität von Inhalten dar. Idealerweise würde anstelle von install.sh alle benötigte Funktionalität ausschließlich vom Ersteller der Distribution („Schulstick“) ermöglicht und durch eine unprivilegierte Ausführung von install_test.sh getestet werden. Eine solche Umsetzung ist mittelfristig denkbar. Bis dahin können install.sh und install_test.sh eine deutliche Vereinfachung der Erstellung neuer Lerninhalte ermöglichen. Wenn vom Ersteller der Distribution install.sh und install_test.sh aller Lerninhalte reviewed werden, kann das Schadenspotential durch böswillige Ersteller von Inhalten als niedrig eingeschätzt werden.

Neue Tutorials erstellen

Tutorials im Lernportal auf dem Schulsstick testen

Inhalte veröffentlichen

FAQ

Etwas funktioniert nicht — Wo kann ich Fehler melden und um Korrektur oder Hilfe bitten?

Ich habe einen Fehler gefunden — Wie kann ich etwas berichtigen und meine erste Änderung veröffentlichen?

Features auf verschiedenen Umgebungen