Konzeption einer Benutzerdokumentation
Die Benutzerdokumentation ist ein wesentlicher Bestandteil der Softwareentwicklung und ein kritischer Faktor für die Benutzererfahrung und -zufriedenheit. In dieser Arbeit wurde eine solche Dokumentation für die Software repeatio.de konzipiert. Die Dokumentation ist verfügbar unter: https://rllyyy.github.io/repeatio-docs/

1. Einleitung
1.1 Relevanz des Themas
Die Benutzerdokumentation ist ein wesentlicher Bestandteil der Softwareentwicklung und ein kritischer Faktor für
die Benutzererfahrung und -zufriedenheit. Sie dient als Brücke zwischen der Technologie und ihren Anwendern, indem
sie komplexe Prozesse in verständliche Anweisungen übersetzt. Eine effektive Dokumentation ermöglicht es den
Benutzern, das volle Potenzial eines Produkts zu erschließen und unterstützt sie dabei, eventuelle Probleme
selbstständig zu lösen.[1] Diese Arbeit zeigt anhand
eines Praxisbeispiels, wie eine solche Benutzerdokumentation aussehen kann.
1.2 Ziele der Arbeit
Das Hauptziel der vorliegenden Arbeit besteht in der Konzeption einer Benutzerdokumentation. Zwischenziele bilden
die Darstellung der Software, die Analyse der Zielgruppe der Benutzerdokumentation sowie die Ermittlung des
Flesch-Reading-Ease- und Flesch-Kincaid-Index.
1.3 Aufbau der Arbeit
In den Grundlagen der Arbeit wird zunächst die Software, für die die Benutzerdokumentation erstellt wird,
vorgestellt (Kapitel 2.1), bevor eine Zielgruppenanalyse der Benutzerdokumentation durchgeführt wird (Kapitel
2.2). Anschließend wird in Kapitel 2.3 die Software in die Softwareprodukttypen nach Lehman eingeordnet. Im
Hauptteil wird die Benutzerdokumentation erstellt (Kapitel 3.1) sowie der Flesch-Reading-Ease-Index
und Flesch-Kincaid-Index für eine typische Seite der Dokumentation ermittelt (Kapitel 3.2).
Abschließend werden in Kapitel 3.3 Verbesserungsmöglichkeiten herausgearbeitet.
2. Grundlagen
2.1 Darstellung der Software
Repeatio
ist eine selbstentwickelte Open-Source[2]
Online-Lernplattform, die sich auf die gezielte Vorbereitung auf Prüfungen konzentriert. Obwohl sich die Software
derzeit noch in einem aktiven Entwicklungsstadium befindet und daher keine endgültige Version vorliegt, ist sie
jetzt schon über die Website www.repeatio.de
öffentlich zugänglich. Die Plattform bietet Funktionen zur Erstellung und Bearbeitung von Lernmodulen, die
unterschiedliche Fragetypen wie Multiple Choice, Multiple Response, Lückentext und Zuordnungsaufgaben
unterstützen. Ziel ist es, klassische Lernmethoden wie physische Lernkarten zu ersetzen und stattdessen umfassende
Möglichkeiten von interaktiven Lernmöglichkeiten bereitzustellen.
Besonders positiv an dem Software-System ist neben der Interaktivität, dass Fragen genauso wie in der späteren
Prüfung aufgebaut sind. Die Software bietet darüber hinaus die Möglichkeit, Fragen mittels der Merkfunktion
abzuspeichern, was ein gezieltes und effektives Lernen ermöglicht.
Während Software wie Anki oder StudySmarter nur einfache Aufgaben wie
Multiple Choice erlauben, können mit repeatio auch komplexere Zuordnungs- und Multiple Response
Aufgaben abgebildet werden.
2.2 Zielgruppenanalyse
Die Benutzerdokumentation richtet sich an fortgeschrittene Nutzer*innen der Website, die Module selbst erstellen,
teilen sowie Fragen mit Hilfe von MarkDown gestalten wollen. Die Nutzerbasis der Website besteht zum
Großteil aus Personen im Alter von 16 bis 35 Jahre, die sich aktiv auf Prüfungen vorbereitet. Zu dieser
Personengruppe zählen insbesondere Schüler*innen, Auszubildende, und Student*innen, aber auch Personen, die
sonstige Prüfungen ablegen (z.B. Führerschein). Die geographische Verteilung konzentriert sich zum aktuellen
Zeitpunkt auf den deutschsprachigen Raum. Für die Zielgruppe ist die kostenlose Bereitstellung der Software und
Dokumentation besonders attraktiv, da sie häufig nur über begrenzte finanzielle Ressourcen verfügt. Die Zielgruppe
zeichnet sich zudem durch einen ausgeprägten Lernwillen aus. Die technologische Kompetenz der Nutzer variiert
stark. Einige Nutzer sind mit komplexeren Webanwendungen vertraut, während andere Anleitungen benötigen, um die
grundlegenden Funktionen der Plattform effektiv zu nutzen. Bisherige persönliche Beobachtungen deuten darauf hin,
dass erfahrene Nutzer*innen bei der Erstellung von Inhalten tendenziell Geräte mit größeren Bildschirmen
bevorzugen.
Das Ziel der Benutzerdokumentation ist es, eine umfassende und verständliche Informationsressource
bereitzustellen, die den Nutzerinnen und Nutzern von repeatio dabei hilft, die Website effektiv zu
nutzen. Die Dokumentation soll die Anwender in die Lage versetzen, die Funktionen der Software zu verstehen,
erfolgreich zu navigieren und optimal von den gebotenen Lernmöglichkeiten zu profitieren. Dabei geht es nicht nur
um die Vermittlung technischer Details, sondern auch um eine praxisnahe Anleitung und Unterstützung bei der
Erstellung und Nutzung von Lernmodulen. Der Fokus der Dokumentation liegt insbesondere darauf Leserinnen und
Lesern Gestaltungsmöglichkeiten der Fragen näherzubringen.
Für eine effektive Nutzung der Software werden grundlegende Englisch- und Technologiekenntnisse vorausgesetzt.
Erste Berührungspunkte mit MarkDown, HTML (Hypertext Markup Language) und CSS sind von Vorteil aber
keinesfalls Voraussetzung.
2.3 Softwareprodukttyp
Die Software ist am ehesten den P-Typ-Systemen nach Lehman (1980) zuzuordnen.[3]
Größere Anpassungen sind nach Veröffentlichung der Vollversion (Version 1.0) nicht geplant. Lediglich kleinere
Punkte wie das Beheben von Sicherheitsprobleme, die z.B. durch die Verwendung von Node.js-Modulen immer wieder
auftreten, sollen kontinuierlich behoben werden.
Die Software ist kaum von sich ändernden Rahmenbedingungen betroffen, schließlich werden nur selten neue
Aufgabentypen erfunden. Zudem besitzt die Software kaum Schnittstellen (APIs) zu anderen Systemen, die eine
kontinuierliche Anpassung erforderlich machen.
Würde es sich stattdessen um ein kommerzielles Produkt handeln, müssten eventuell häufiger Anpassungen
vorgenommen werden, um den höheren Ansprüchen der Nutzer*innen gerecht zu werden und eine hohe Zufriedenheit zu
garantieren.[4] Die Software wäre dann eher den
dynamischen Systemen (embedded-type) zuzuordnen.
3. Hauptteil
3.1 Praxisbeispiel Benutzerdokumentation
Für die Erstellung der Online-Benutzerdokumentation wurde Docusaurus verwendet.
Docusaurus ist ein Open Source Werkzeug zur Erstellung von statischen Webseiten auf Basis von
Technologien wie MarkDown und React. Gegenüber der gedruckten Softwaredokumentation bietet die
Online-Dokumentation Vorteile wie die schnelle Aktualisierbarkeit, die leichte Zugänglichkeit, die Möglichkeit zur
Verlinkung von Inhalten sowie den Einsatz von Videos oder Animationen.
Die Online-Dokumentation liegt einerseits als Software sowie anderseits in PDF-Form im Anhang dieser Arbeit vor.
Um die Online-Benutzerdokumentation lokal zu starten, müssen zunächst alle erforderlichen Abhängigkeiten mit dem
Befehl "npm install" heruntergeladen werden. Anschließend kann der lokale Server mit dem
Befehl "npm run serve" gestartet werden. Standardmäßig läuft dieser auf dem
Port 3000 (http://localhost:3000). Weitere Befehle sind in der README-Datei zu entnehmen.
3.2 Flesch-Reading-Ease-Index und Flesch-Kincaid-Index
Der Flesch-Reading-Ease-Index beträgt für die Seite 22 der Dokumentation (Seite XXV in dieser
Arbeit) 38,67:
Obwohl der Wert zunächst sehr niedrig erscheint, ist zu beachten, dass der Flesch-Reading-Ease-Index
für die englische und nicht für die deutsche Sprache entwickelt wurde.[5]
Nach dem Ansatz von Amstad (1978) beträgt der REIdeutsch 60,78[6].
Für die gleiche Seite ergibt sich ein Flesch-Kincaid-Index von 10,32:
3.3 Verbesserungsmöglichkeiten
Bei der Erstellung dieser Benutzerdokumentation musste aufgrund der begrenzenten Seitenanzahl von 25 Seiten
einige Funktionen der Software ausgelassen werden. Hierzu zählen insbesondere Hilfestellungen für Nutzer*innen,
die noch nicht mit den Grundfunktionen der Software vertraut sind.
Die hier beschriebene Benutzerdokumentation beschränkt sich aktuell nur auf den deutschsprachigen
Raum. Die Software soll aber auch von englischsprachigen Nutzer*innen genutzt werden können. Mit i18n
bietet Docusaurus eine Möglichkeit, Übersetzungen in die Dokumentation zu integrieren.[7]
Eine weitere Verbesserungsmöglichkeit besteht in einer integrierten Suchfunktion, welche Nutzerinnen und Nutzer
eine schnelle Auffindung von Informationen ermöglicht.[8]
Der Ansatz lässt sich durch die Einbindung einer künstlichen Intelligenz (KI), mit der Anwender*innen
direkt kommunizieren können, fortführen.
Zudem könnten die Vorteile der Online-Dokumentation durch die Verwendung von GIFs oder kurzen Erklärvideos
anstelle von Bildern weiter ausgenutzt werden. Darüber hinaus sollte geprüft werden, ob eine direkte Integration
der Dokumentation in die Software sinnvoll ist.
4. Schlussbetrachtung
Im Fokus dieser Arbeit stand die Konzeption einer Benutzerdokumentation für fortgeschrittene Nutzerinnen und Nutzer der Software repeatio. Dafür wurde zunächst eine Zielgruppenanalyse durchgeführt, sowie die Software als P-System identifiziert. Darauf aufbauend wurde in der Benutzerdokumentation zunächst eine kurze Übersicht über wichtige Themen gegeben, bevor die Fragetypen detailliert vorgestellt sowie das Erstellen und Exportieren von Modulen erläutert wurde. Anschließend wurde aufgezeigt, wie Fragen hinzugefügt und bearbeitet werden können. Der Schwerpunkt der Benutzerdokumentation lag auf dem Fragen-Editor und dessen umfassende Einsatzmöglichkeiten in Verbindung mit MarkDown. Abschließend wurden die verschiedenen Übungsmodi behandelt sowie im FAQ die wichtigsten Fragen beantwortet.
Mit der Weiterentwicklung der Software ist die Benutzerdokumentation kontinuierlich anzupassen. Neben neuen Features, sollen aber auch neue häufig auftretende Fragen und Probleme in die Benutzerdokumentation integriert werden.
Bei der Analyse der Zielgruppe in Kapitel 2.2 musste auf die persönliche Erfahrung zurückgegriffen werden, da das Projekt keine Cookies zur Analyse des Nutzerverhalten einsetzt. Bei der erstellten Dokumentation handelt es sich um eine externe Benutzerdokumentation. Ein Kritikpunkt an diesem Ansatz ist, dass nach Grünwied (2012) Webanwendungen eigentlich selbsterklärend sein sollten und die Dokumentation direkt in die Software eingebettet sein sollte.[9] Jedoch würde eine solche direkte Integration die Gefahr, dass nicht fortgeschrittene Nutzer*innen der Software schnell überfordert werden.
I. Literaturverzeichnis
[Anstad, T., 1978] Amstad, T. (1978): Wie verständlich sind unsere Zeitungen? Zürich: Studenten-Schreib-Service
[Doose, D., o.D.] Doose, D. (o.D.): Softwaredokumentation (MIP401) – Verfahren und Systeme der Softwaredokumentation. Stuttgart: AKAD Bildungsgesellschaft mbh
[Eichstädt, T., 2024] Eichstädt, T./Spieker, S. (2024): 52 Stunden Informatik - Was jeder über Informatik wissen sollte, 2. Auflage. Wiesbaden: Springer Fachmedien
[Friedrich, D., o.D.] Friedrich, D. (o.D.): Softwaredokumentation und Softwarewartung (MIP403) – Verfahren und Systeme der Softwaredokumentation. Stuttgart: AKAD Bildungsgesellschaft mbh
[Grünwied, G., 2012] Grünwied, G. (2012): Software-Dokumentation: Grundlagen – Praxis – Lösungen, 3., aktualisierte Auflage. Tübingen: Expert Verlag GmbH
[Lehman, M., 1980] Lehman, M. (1980): Programs, Life Cycles, and Laws of Software Evolution. In: Proceedings of the IEEE, 68 (9). New York: IEEE, S. 1060-1076
[Meta Platforms, 2024a] Meta Platforms/Lorber, S. (2024): i18n – Introduction. Docusaurus, https://docusaurus.io/docs/i18n/introduction (Abgerufen am 16.03.2024)
[Meta Platforms, 2024b] Meta Platforms/Lorber, S. (2024): Search. Docusaurus, https://docusaurus.io/docs/search (Abgerufen am 19.03.2024)
[Theilig, MM., 2021] Theilig, MM./Rechenberg, P./Mössenböck, H. (2021): Programmierung. In: Hennecke, M./Skrotzki, B. (Hrsg.): HÜTTE – Das Ingenieurwissen. Berlin: Springer
II. Anhang
Inhaltsverzeichnis – Anhang
1. Was ist Repeatio?
.....................................................................................................................
IV
2. Frage Typen
............................................................................................................................
VIII
3. Module hinzufügen
..................................................................................................................
XI
4. Module exportieren
...............................................................................................................
XIV
5. Fragen hinzufügen
...................................................................................................................
XV
6. Fragen bearbeiten
..................................................................................................................
XVI
7. Fragen-Editor
.........................................................................................................................
XVII
8. Modi
......................................................................................................................................
XXV
9. FAQ
......................................................................................................................................
XXVII
[1] Vgl. Theilig, MM. (2021) S. 51 f.; vgl. Doose, D. (o.D.) S. 6; vgl. Friedrich, D. (o.D.) S. 55
[2] Open Source bezeichnet Software, deren Quellcode öffentlich zugänglich ist und von Dritten eingesehen, genutzt und auch modifiziert werden darf. (Vgl. Eichstädt, T. [2024] S. 266)
Der Quellcode des Projekts findet sich auf GitHub: https://github.com/Rllyyy/repeatio
[3] Vgl. Lehman, M. (1980) S. 1063; vgl. Friedrich, D. (o.D.) S. 15
[4] Vgl. Friedrich, D. (o.D) S. 16
[5] Vgl. Amstad, T. (1978) zitiert nach Doose, D. (o.D.) S. 65
[7] Vgl. Meta Platforms (2024a) o.S.
[8] Vgl. Meta Platforms (2024b) o.S.
[9] Vgl. Grünwied, G. (2012) o.S. zitiert nach Doose, D. (o.D.) S. 10