Der Entwickler Terence Eden bezahlte Testpersonen mit je 25 €, um den Installationsprozess seines Open-Source-Projekts „ActivityBot“ anhand der README-Datei live per Screen-Sharing und „Think-Aloud“-Verfahren zu testen. Die Sitzungen im Gesamtwert von rund 150 € offenbarten gravierende Entwickler-Biases, darunter fehlende Beschreibungen des Software-Nutzens, fehlerhafte Demo-Links, unklare Berechtigungsannahmen und verwirrende Witze. Das Experiment belegt, dass menschliches Usability-Testing für technische Dokumentationen unverzichtbar ist, um reale Benutzerhürden aufzudecken, die weder durch eigene Betriebsblindheit noch durch reine KI-Simulationen vollständig identifiziert werden.
Wichtigste Punkte
Finanzielles Test-Setup: Investition von ca. 150 € (25 € Honorar pro Proband für eine Stunde) zur Rekrutierung von Testpersonen über Mastodon.
Think-Aloud-Methodik: Durchführung von Live-Videokonferenzen mit Bildschirmfreigabe, bei denen die Teilnehmer ihre Handlungen, Zweifel und Frustrationen in Echtzeit verbalisierten.
Zentrale Dokumentationsmängel: Aufdeckung grundlegender Versäumnisse wie das Fehlen einer prägnanten Software-Definition, unvollständige Installationsvoraussetzungen (z. B. Webserver-Berechtigungen), fehlerhafte Hyperlinks und unklare Handhabung versteckter Dateien.
Entwickler-Biases (Kognitive Verzerrungen): Identifikation unbewusster Autorenannahmen, wonach Befehle universell sudo erfordern, CLI-Syntaxoptionen (-foo vs. --foo) intuitiv sind oder Neustarts vorausgesetzt werden.
Kommunikatives Rauschen: Erkenntnis, dass integrierte Witze oder Anekdoten vom eigentlichen Zweck ablenken und bei unerfahrenen Anwendern zu Irritationen führen.
Nutzungsverhalten: Die Mehrheit der Anwender liest READMEs über Web-Oberflächen (z. B. GitLab) statt rein im Terminal, weshalb Markdown-Strukturen und visuelle Formatierungen entscheidend sind.
Diskussions-Highlights
Usability-Testing als UX-Prinzip: Diskussionsteilnehmer vergleichen den Ansatz mit klassischen Methoden wie „Hallway Testing“ (bekannt aus der UX-Forschung nach Stephen Krug) und „Friction Logs“ (angewandt unter anderem bei Stripe).
Interne Onboarding-Praxis: Mehrere Kommentatoren berichten, dass das Einbinden von Auszubildenden oder neuen Teammitgliedern als Testleser für bestehende READMEs ein hocheffektives, etabliertes Mittel zur dauerhaften Qualitätssicherung darstellt.
Automatisierung und Toolchains: Als Alternative zu manuellen Installationsanleitungen wird der Einsatz von deklarativen Werkzeugen wie Nix, direnv oder containerisierten Umgebungen (Docker) genannt, um manuelle Fehlerquellen von vornherein auszuschließen.
Kritik und Grenzen von KI-Tests: Während einige Nutzer vorschlagen, KI-Agenten in Sandboxes (unter Nutzung von Tools wie Playwright) zur Dokumentationsprüfung einzusetzen, betonen andere, dass Künstliche Intelligenz zwar technische Ausführungsfehler erkennt, jedoch menschliche Frustrationen, unpassenden Humor oder unklare Konzeptsprache nicht adäquat bewerten kann, da Agenten Probleme fehlerhaft mit voller Zuversicht ausführen.
Dokumentation als Zustandsmaschine: Ein technischer Kommentar vergleicht das Schreiben von Dokumentationen mit dem Schreiben von Code: Jedes Dokument muss den Leser über validierte Vor- und Nachbedingungen (Pre- und Postconditions) von einem Startzustand in einen Zielzustand überführen.
Glossar
README: Eine Textdatei im Stammverzeichnis eines Softwareprojekts, die grundlegende Informationen zur Installation, Konfiguration und Verwendung der Software bereitstellt.
Usability-Testing: Eine Methode der empirischen Benutzerforschung, bei der die Benutzerfreundlichkeit und Verständlichkeit eines Produkts oder einer Dokumentation durch echte Anwender unter Beobachtung geprüft wird.
Developer Bias (Entwickler-Bias): Die kognitive Verzerrung von Softwareentwicklern, fälschlicherweise vorauszusetzen, dass Anwender über denselben Wissensstand, dieselben Berechtigungen und dieselbe Systemumgebung verfügen.
Think-Aloud-Methode: Ein qualitatives Testverfahren, bei dem Testpersonen während der Bearbeitung einer Aufgabe ihre Gedanken, Interpretationen und Hürden kontinuierlich laut aussprechen.
CLI (Command Line Interface): Eine textbasierte Befehlszeilenschnittstelle zur Steuerung von Betriebssystemen und Programmen durch das Eintippen von Befehlen.
Markdown: Eine leicht lesbare Auszeichnungssprache, die entwickelt wurde, um Textdateien mit einfachen Formatierungen (wie Überschriften, Listen und Links) zu versehen.
Nix / direnv: Paketverwaltungs- und Umgebungswerkzeuge zur isolierten, reproduzierbaren Konfiguration von Software-Abhängigkeiten und Entwicklungsumgebungen.
LLM (Large Language Model): Ein auf künstlicher Intelligenz basierendes Sprachmodell, das große Textmengen verarbeitet und menschenähnlichen Text analysieren oder generieren kann.
Friction Logs: Dokumentierte Protokolle über sämtliche Reibungspunkte, Barrieren und Frustrationen, die ein Anwender bei der Interaktion mit einem Produkt oder einer Anleitung erfährt.