Manifest

Eine Vereinbarung darüber, wie Methodensammlungen abgelegt werden – damit sie geteilt, verzweigt und wieder zusammengeführt werden können.

Fassung 1 · Änderungen an diesem Manifest

Warum es dieses Dokument gibt

Das Wertvolle an Ableger ist nicht die Website und nicht die Eingabemaske. Es ist die Sammlung selbst – und die Vereinbarung darüber, wie sie abgelegt ist (das Protokoll).

Oberflächen veralten, werden ersetzt, gehen kaputt. Ein Ordner mit Textdateien nicht. Wer Website und Formular austauscht, sich aber an dieses Manifest hält, bleibt anschlussfähig: Methoden lassen sich in beide Richtungen übernehmen, ohne sie abzutippen.

Dieses Dokument gehört deshalb zu den Inhalten, nicht zur Software – es steht bewusst hier auf der Projekt-Website und nicht im Website-Repo. Ein maschinenlesbarer Teil (der Feldkatalog als strukturierte Datei statt nur als Tabelle unten) ist in Arbeit; bis dahin ist dieser Text die verbindliche Referenz.

Teil A – Prinzipien des Teilens

1. Offen ist der Normalfall

Jede Methode ist frei einsehbar und unter einer offenen Lizenz nutzbar. Das schließt ausdrücklich die vier Freiheiten ein: behalten, weiterverwenden, verändern, weitergeben. Eine Methode, die nicht verändert werden darf, zieht keinen Mehrwert aus dieser Systematik.

2. Anpassen ist erwünscht, nicht geduldet

Material wird umso wirksamer, je genauer es auf eine konkrete Situation zugeschnitten ist. Sie verliert mit ihrer Spezifität aber auch ihre Wirksamkeit in anderen Kontexten. Wer beides gleichzeitig will, bekommt meist keines von beidem.

Ableger löst das nicht durch Kompromiss, sondern durch Trennung: Die Methode bleibt allgemein und auffindbar (kleinster gemeinsamer Nenner, bevor es eine ganz andere Methode ist). Die Variante darf so konkret, lokal und eigensinnig sein, wie sie will. Eine Variante für einen konkreten Kontext ist kein Sonderfall, sondern genau das, wofür es die Sammlung gibt.

3. Herkunft bleibt sichtbar

Wer eine Methode eingebracht hat, wer eine Variante ausgearbeitet hat und worauf beide sich stützen wird mitgeführt. Damit bleibt auch der Diskurs über die Inhalte und Entscheidungen möglich. Namensnennung ist keine Formalie, sondern die Gegenleistung fürs Teilen und der Beginn einer Diskussion über die Inhalte.

4. Die Lizenz hängt am konkreten Werk

Die Verwendung von (offenen) Lizenzen ermögliche das Weiterverwenden.
Nicht die Methode als Idee ist urheberrechtlich geschützt, sondern der Text, der sie beschreibt. Die Lizenz gehört deshalb dorthin, wo dieser Text steht: zur Variante.

5. Beitragen darf man auf dem Weg, den man beherrscht

Über ein Formular, über die Weboberfläche der Versionsverwaltung, über die Kommandozeile, mit einem Texteditor. Kein Weg ist privilegiert. Was zählt, ist das Ergebnis im Ordner.

Teil B – Prinzipien der Datenhaltung

6. Der Ordner ist die Quelle

Jede Datei muss mit einem einfachen Texteditor les- und änderbar sein. Keine Information darf ausschließlich in einer Datenbank, einer Konfiguration oder einer Oberfläche existieren.

7. Verweise gehen auf stabile Bezeichner

Ein Titel ist für die Anzeige bestimmt. Er darf sich jederzeit ändern, ohne dass etwas zerbricht. Ein eindeutiger Identifier sollte menschenlesbar sein und darf nicht geändert werden.

8. Nichts speichern, was sich ableiten lässt

Abgeleitetes wird bei der Anzeige berechnet, nie als eigenes Datum gepflegt, damit keine Daten auseinanderdriften. Das sind z. B.:

• Änderungsdaten aus der Versionsgeschichte
• Sichtbarkeit einer Methode
• Spannen aus Einzelwerten

9. Die Regeln sind (maschinell) prüfbar

Alles in Teil D ist maschinell überprüfbar formuliert. Eine Sammlung kann dadurch jederzeit gegen dieses Manifest geprüft werden.

10. Verzweigbar und rückführbar

Zwei Sammlungen, die sich an dieses Manifest halten, müssen Inhalte gegenseitig übernehmen können.

Teil C – Das Datenmodell

Zwei Ebenen

Die Regel, nach der ein neues Feld einsortiert wird, lautet:

• Identifiziert das Feld die Methode und macht sie auffindbar? → Methode.
• Alles andere ist Durchführungs-orientiert → Variante.

„Titel“, „Kurzbeschreibung“, „Zielgruppe“ identifizieren und machen auffindbar. „Dauer“, „Material“, „Lizenz“ beschreiben, wie eine konkrete Ausarbeitung durchgeführt wird – auch wenn sie bei allen Varianten zufällig gleich ausfallen.

Keine Vererbung

Ein Feld lebt an genau einer Stelle. Wo die Methoden-Seite einen Gesamtwert zeigen soll (z. B. „20–35 Minuten“), wird dieser bei der Anzeige aus den Varianten berechnet – nicht gepflegt. Wo es scheinbar Vererbung braucht, verstecken sich meist zwei verschiedene Felder mit unterschiedlicher Bedeutung; die werden getrennt (vgl. herkunft und quellen).

Verzeichnisstruktur

<sammlung>/
├── ableger.yml                     # Protokoll-Version und Vokabular
├── LICENSE
├── methoden/
│   └── <methoden-kennung>/
│       └── index.md
└── varianten/
    └── <methoden-kennung>--<varianten-kennung>/
        ├── index.md
        └── <anhänge>               # direkt daneben, kein Unterordner

Ein Ordner ist eine Einheit, der alle notwendigen Datenpunkte enthält. Er ist in seinen Inhalten autark.

Bezeichner

Jede Methode und jede Variante hat eine Kennung, die folgenden Regeln entspricht: kurz, sprechend, nur a-z, 0-9, - und _. Bei der Methode ist sie zugleich der Ordnername; bei der Variante der zweite Teil des Ordnernamens (<methoden-kennung>--<varianten-kennung>).

Die Kennung wird bei der Erstellung einmalig vergeben und danach nie geändert – auch dann nicht, wenn Titel bzw. Untertitel sich ändern. Sie ist der stabile Bezugspunkt; Titel und Untertitel dienen hingegen der Anzeige und können geändert werden.

Varianten verweisen über die Methoden-Kennung auf ihre Methode, nie über den Titel.

Warum sprechende Kennungen und keine technischen IDs: Zwei Sammlungen sollen erkennen können, dass sie dieselbe Methode enthalten. Das leistet nur eine über Forks hinweg gleichbleibende, lesbare Kennung. Wir haben uns gegen eine zusätzliche Absicherung mit einer zufälligen Zeichenfolge entschieden. Das hat den Preis, dass zwei unabhängig entstandene Sammlungen zufällig dieselbe Kennung für zwei verschiedene Methoden vergeben können. Bei einer Zusammenführung (Git-Merge) macht das aber keinen Unterschied: es wird ein Konflikt an derselben Datei sichtbar, kein Fall verschwindet unbemerkt. Ein Zufallswert würde zudem der (menschlichen) Lesbarkeit schaden.

Feldkatalog

Methode (methoden/<kennung>/index.md)

Der Dokumentenkörper bleibt leer, da die Inhalte zur Variante gehören.

Variante (varianten/<methode>--<kennung>/index.md)

Der Dokumentenkörper enthält die Durchführung, gegliedert in Vorbereitung, Ablauf, Hintergründe.

Nicht gespeicherte Daten

• Änderungsdatum, Erstellungsdatum und Bearbeiter*in kommen aus der Versionsgeschichte.
• Die Sichtbarkeit der Methode ergibt sich daraus, ob mindestens eine Variante veröffentlicht ist.
• Dauer- und Gruppengrößen-Spannen der Methode werden aus den Feldern der Varianten berechnet.

Vokabular und Version

Beides steht in ableger.yml an der Wurzel der Sammlung. Sie sind damit Teil der Inhalte, nicht der Website.

Das Feld heißt bewusst protokoll_version, nicht manifest_version: Es zählt die Kompatibilität des Datenprotokolls (Teil C und D dieses Dokuments), nicht eine Version des Fließtexts. Auf der Website wird derselbe Wert Leser*innen gegenüber als „Manifest-Version“ beschriftet – der technische Feldname bleibt unverändert, nur die Anzeige-Bezeichnung ist zugänglicher.

protokoll_version: 1

vokabular:
  zielgruppe: [Kinder, Jugendliche, Erwachsene, Senior*innen]
  kompetenzbereich: [Fachkompetenz, Methodenkompetenz, Sozialkompetenz, Selbstkompetenz]
  lizenz: [CC0, CC-BY 4.0, CC BY-NC 4.0]

kategorie und tags haben bewusst kein Vokabular und bleiben offen.

Teil D – Regeln

1. Jede Variante verweist auf eine existierende Methoden-Kennung.
2. Kennungen sind je Ebene eindeutig (Methoden untereinander, Varianten je Methode untereinander).
3. Der Ordnername einer Methode ist ihre Kennung.
4. Der Ordnername einer Variante ist <methoden-kennung>--<varianten-kennung>.
5. Alle Kennungen bestehen nur aus a-z, 0-9, - und _.
6. Eine Kennung ändert sich nach der ersten Vergabe nicht mehr.
7. Jeder Ordner enthält genau eine index.md.
8. Alle Pflichtfelder sind vorhanden und nicht leer.
9. Felder mit Vokabular enthalten nur zugelassene Werte.
10. gruppengroesse_min ist nicht größer als gruppengroesse_max.
11. Der Dokumentenkörper einer Methode ist leer.
12. Kein abgeleitetes Feld ist gespeichert.
13. Jede in anhaenge genannte Datei existiert im selben Ordner.
14. protokoll_version ist vorhanden und wird unterstützt.

Verstöße werden als Fehler gewertet. Eine Sammlung, die sie nicht besteht, hält dieses Manifest nicht ein und ist damit nicht mehr Kompatibel zu anderen Ablegern.

Eine Referenzimplementierung dieser Regeln (scripts/validate.rb) ist Teil des Vorlagen-Repos für die Website.

Diskutierte Regeln, die nicht aufgenommen wurden:

• Jede Methode hat mindestens eine Variante.
  • Eine Methode ohne (veröffentlichte oder unveröffentlichte) Variante kann gerade in Arbeit sein. Sie stört die Datenlogik nicht, auf der Website wird sie nicht angezeigt (vgl. Teil C).
• Sämtliche Abhängigkeiten zu verwendeten Werkzeugen (Hugo, Decap CMS, Gitea, Hosting, Deploy-Verfahren, Layout, Farbschema, Suchfunktion).
  • Sollen austauschbar sein. Wenn die Pflege von Feldern von einem Werkzeug nicht unterstützt wird, eignet sich das Werkzeug nicht.

Teil E – Anschluss an bestehende Standards

Die Zweiteilung in Methode und Variante ist keine Erfindung dieses Projekts. Sie entspricht der bibliothekswissenschaftlichen Unterscheidung zwischen Work und Expression (IFLA LRM, vormals FRBR), die schema.org in vereinfachter Form als exampleOfWork / workExample übernommen hat.

Für die Beschreibung von Bildungsmaterialien existiert im deutschsprachigen Raum das Allgemeine Metadatenprofil für Bildungsressourcen (AMB) der DINI-AG KIM, das als Grundlage für den Suchindex OERSI verwendet wird. Ableger übernimmt dessen Feldnamen nicht, weil wir davon ausgehen, dass deutsche, verständliche Bezeichnungen für die Menschen, die hier eintragen, wichtiger sind.

Wir dokumentieren die Zuordnung, damit eine Sammlung ohne Änderung am Datenmodell für solche Suchdienste bereitgestellt werden kann. Diese Zuordnung beschreibt, wie portiert werden könnte, erzeugt aber noch keine strukturierten Daten (z. B. JSON-LD). Dieser Schritt ließe sich später implementieren.

Was ist der portable Datensatz? In AMB werden einzelne Ressourcen beschrieben. Bei Ableger entspricht das der Variante (die konkrete Ausarbeitung mit Durchführung, Material, Lizenz). Die Methode ist die Abstraktion darüber (exampleOfWork/workExample, s. u.), analog zu Work vs. Expression in IFLA LRM. Praktisch bekäme also jede Variante ihren eigenen AMB-Datensatz, der auf den Datensatz ihrer Methode verweist.

AMB hat nur drei Pflichtfelder: id, type, name.

Weitere Felder:

kompetenzbereich und lernchancen liegen inhaltlich nah beieinander; da AMB nur ein einziges teaches-Feld kennt, bildet lernchancen (die konkreteren, stichpunktartigen Lernchancen) diese Entsprechung ab, kompetenzbereich bleibt unübersetzt. AMB verlangt keine vollständige Abbildung aller Felder, nur dass die Pflichtfelder gedeckt sind und nichts Vorhandenes falsch zugeordnet wird.

Warum genau das Zwei-Ebenen-Modell Methode/Variante (statt eines einfacheren Modells) fachlich sinnvoll ist, mit weiteren Quellen: Konzept und Grundprinzipien, „Warum dieses Datenmodell“.

Quellen

• IFLA Library Reference Model / FRBR – Work-Expression-Manifestation-Item: Code4Lib Journal, IFLA Transition Mappings
• schema.org exampleOfWork / workExample: schema.org, Schema Bib Extend Community Group
• DINI-AG KIM, Allgemeines Metadatenprofil für Bildungsressourcen (AMB): Spezifikation, GitHub

Änderungen an diesem Manifest

protokoll_version wird erhöht, sobald sich etwas ändert, das bestehende Sammlungen ungültig machen würde (ein neues Pflichtfeld, ein umbenanntes Feld, eine verschärfte Regel). Ergänzungen, die alte Sammlungen gültig lassen, ändern die Version nicht.

Sammlungen mit unterschiedlicher Protokoll-Version können nicht ohne Weiteres zusammengeführt werden. Deshalb steht die Version in der Sammlung selbst (ableger.yml), nicht nur hier auf der Website.