Konzeption einer Benutzerdokumentation

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 REI_deutsch 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

---