Zum Inhalt

3.3 Dokumentation

Der Zweck einer DSE-Dokumentation besteht neben genereller, editionsphilologischer und technischer Informationen für die Nutzenden darin, die Nachnutzung der DSE zu ermöglichen bzw. zu vereinfachen. Für Nutzende und Nachnutzende wird nachvollziehbar gemacht, wie die Editionsdaten zustande gekommen sind, wer sie erstellt hat, wann sie erstellt wurden, wo sie erstellt wurden, warum sie erstellt wurden. Eine gute Übersicht zum Thema Nachnutzung von Daten gibt die Universitätsbibliothek Zürich hier.

Die DSE-Dokumentation ist ein zentraler Bestandteil einer DSE, deshalb sollten schon in der Planungsphase der Zeitpunkt ihrer Erstellung im Projektplan und die Dokumentations-Verantwortungen im Projektteam festgehalten werden. Wenn möglich gibt es eine Hauptverantwortung für die Dokumentation, die einzelne Aspekte (s.u.) von den betreffenden Spezialist:innen zusammenträgt. In der Planungsphase sollte auch geklärt werden, wie ausführlich und in welchem Datenformat dokumentiert werden muss (s.u.), da die Dokumentation idealerweise bereits während den dokumentierten Arbeitsprozessen geschieht und am Schluss nur noch minimaler redaktioneller Überarbeitung bedarf.

Wir verweisen im Folgenden ausführlich in jedem Punkt auf die Dokumentation der Showcase-Edition, die viele Erläuterungen in diesem Handbuch (insbesondere die Editionsrichtlinien bez. Transkription, Annotation und Kommentierung) gebündelt wiederholt.

Es gilt zu beachten, dass sich bislang nur bedingt standardisierte Dokumentations-Strukturen oder Bezeichnungen für Aspekte der Dokumentation durchgesetzt haben; dies macht den Vergleich der Dokumentationen zuweilen schwierig. Eine Standardisierung wäre wünschenswert, das vorliegende Kapitel versteht sich jedoch nicht als diesbezüglichen Vorschlag, sondern versucht die Dokumentation von (notwendigen und wünschenswerten) Anforderungen aus zu denken.

Was enthält eine DSE-Dokumentation?

Eine DSE-Dokumentation ersetzt den editorischen Kommentar einer gedruckten Edition (der meist knapp die Grundlagen der Textkonstitution und die editorischen Richtlinien erklärt) oder dessen editorisches Nachwort (das zusätzlich die historischen Hintergründe der Edition und editionsphilologische Aspekte erläutert).

Das Editionsmodell der DSE-Dokumentation ergänzt diese klassischen editorischen Erklärungen um ihre Richtlinien zur Erstellung textkritischer und inhaltlicher Annotationen sowie Kommentare in TEI/XML. D.h. es wird erläutert, welche Codierung für welche Formen der Annotation und Kommentierung im TEI/XML verwendet wird. Die DSE wird also nicht nur als Edition (editionsphilologisch), sondern auch als Code (technisch) dokumentiert, wobei diese beiden Aspekte untrennbar miteinander verwoben sind. => Editionsmodell der Showcase-Edition

Die DSE-Dokumentation dokumentiert darum zusätzlich digitale Aspekte, die im Druck keine Entsprechung haben:

Zugänglichkeit und Präsentation

Eine DSE-Dokumentation kann, abhängig von Größe, Komplexität und Innovationsgehalt einer DSE, unterschiedliche Anforderungen zu befriedigen haben, sollte aber gewisse Grundvoraussetzungen in ihrer Präsentation erfüllen: Sie sollte als Dokumentation erkennbar sein und auf der gleichen Ebene wie die Liste der edierten Texte, das Register oder die Suchfunktionen bereitgestellt werden.

Grundsätzlich empfehlen wir, die Unterthemen einer Dokumentation klar zu trennen nach technischen, editionsphilologischen und organisatorischen Themen. Letztere, allgemeine Informationen zum Projektaufbau können auch ausserhalb der Dokumentation präsentiert werden (z.B. als als Projekteinstiegsseite über involvierte Institutionen, Team oder Fördermittel). Eher nicht Teil der Dokumentation sind Hintergrundinformationen zu den edierten Inhalten (als wissenschaftliche Ergänzung im Sinne von Übersichtskommentaren). Zitiervorschläge können in der Dokumentation enthalten sein, die Minimalanforderung ist jedoch, wie bereits erwähnt, für jede distinkte Seite einen Zitiervorschlag gut sichtbar einzublenden. Zum Zitieren einer DSE sollte nicht die Dokumentation konsultiert werden müssen.

Dokumentationstypen

Die minimale Anforderung an eine Dokumentation ist die stichwortartige Erklärung aller sichtbaren/benutzbaren Bestandteile der DSE und entspricht damit eher dem editorischen Kommentar im Druck. Die verschiedenen Aspekte können durch einfache Unterkapitel getrennt auf einer einzelnen Seite vereint werden, was das einfache Generieren eines PDFs ermöglicht. Dies kann für eine kleinere oder wenig komplexe DSE ausreichend sein, insbesondere wenn sie eine bisherige Praxis fortsetzt - in diesem Fall ist es ratsam, in der eigenen Dokumentation auf diejenige vorbildhafter DSE zu verweisen.

Beispielhafte DSE: Minimale Dokumentation

Die Digitale Edition der Reisetagebücher von Johann Conrad Fischer 1794–1851 ist eine optisch ansprechende DSE eines gedruckten, bereits in Buchform kritisch edierten Korpus, das nun primär die Vorteile einfacher Verlinkung und visueller Anreicherung nutzt. Da es auf etablierte Funktionen des TEI Publishers aufbaut, begnügt sich die Dokumentation mit minimalen Angaben zu Editionsgeschichte und Technik sowie zu den Editionsrichtlinien.

Eine ausführliche Dokumentation hat demgegenüber eher den Charakter eines editorischen Nachworts und wird zur besseren Übersichtlichkeit in mehrere Unterseiten aufgeteilt. Je stärker ein DSE-Projekt innerhalb einer community Vorbild-Charakter haben soll und/oder je innovativer ein DSE-Projekt ist, desto ausführlicher sollte die Dokumentation ausfallen.

Beispielhafte DSE: Ausführliche Dokumentation

Im folgenden werden zwei DSE vorgestellt, bei denen es sich in technischer Hinsicht um 'haute couture' Editionen handelt und die entsprechend ausführliche Dokumentationen aufweisen.

Die DSE Der Sturm vereint und ediert eine Vielzahl sehr unterschiedlicher Dokumente rund um die internationale Avantgarde des 20. Jahrhunderts. Dadurch sind verschiedene, komplexe Editionsrichtlinien etc. notwendig. Sie verfügt über eine ausführliche und klar gegliederte Dokumentation ihrer digitalen Methodik, ihrer TEI/XML-Codierung und ihrer Datenressourcen (mitsamt Schnittstelle zum eigenen Datenzugriff).

Die bereits früher erwähnte Briefkorrespondenz-DSE hallernet ist hinsichtlich ihrer Datenbank eines der ambitioniertesten Projekte der letzten Jahre. Das zeigt sich auch in ihrer Dokumentation. Hierfür wurde eine eigene Subdomain fast ausschliesslich auf Englisch geschaffen, die drei Hauptkategorien (Guidelines/System/Usage) mit Unterkapiteln enthält. Besonderes Augenmerk gilt dabei dabei dem Datenmodell der Metadaten. Die Dokumentation richtet sich primär an ein technisch und editionsphilologisch versiertes Publikum.

Tools und Datenformate

Verwendung von TEI/XML

DSE können ihre Dokumentation im selben Datenformat, in der Regel TEI/XML, verfassen, wie den edierten Text. Dies ist sinnvoll, wenn die Dokumentation mit demselben Tool publiziert werden soll, etwa mit dem TEI Publisher. Zu beachten ist jedoch, dass TEI/XML ein komplexeres Datenformat als normalerweise für eine Dokumentation notwendig darstellt und im Gegensatz zu Markdown (s.u.) kein fixierter Standard ist, sondern mehr Flexibilität zulässt. Das ist insbesondere relevant, wenn Teile der Dokumentation von Mitarbeitenden geschrieben werden, die selbst nicht in den editorischen Prozess involviert sind (z.B. technische Mitarbeitende, die für das Frontend oder die Langzeitsicherung zuständig sind) und sich deshalb in TEI/XML alleine zu diesem Zweck einarbeiten müssten (oder ihre Dateien konvertiert werden müssen).

Fazit: In kleinen Teams, die mit TEI/XML vertraut sind, sind das TEI/XML-Datenformat und zugehörige tools sinnvoll. Eine vereinfachte XML Alternative, die etwa in der TEI Publisher Dokumentation verwendet wird, ist das Format DocBook XML.

Verwendung von Markdown, z.B. zusammen mit MKDocs oder vitepress

Markdown ist ein Datenstandard für technische Dokumentationen und bietet deshalb genügend Funktionalitäten für DSE-Dokumentationen. Es finden sich zudem verschiedene frei zugängliche Python libraries, die mit relativ einfachen Mitteln erlauben, komplexere Dokumentationen zu schreiben. Eine solche Python library, MkDocs wurde für das vorliegende Handbuch verwendet.

Die Dokumentation von hallernet (s.o.) ist Markdown-basiert und wird in einem CI-Workflow automatisiert mit einem gängigen Werkzeug zur Dokumentationserstellung erzeugt (vitepress).

Markdown-Dateien können letztlich auf verschiedene Wege publiziert werden. Für Projekte, die den TEI Publisher verwenden, kann es sinnvoll sein, ihre Markdown-Dateien direkt im Publisher zu publizieren, wie in der TEI Publisher-Dokumentation genauer ausgeführt wird.

Archivierung von Dokumentationen

Bei der gesamthaften Archivierung von DSE in Repositorien kann die Dokumentation zusätzlich auch als eigene Datei (z.B. PDF) abgelegt werden, wie zb. hier in swissubase.