Entwickler schreiben oft schlechte Dokumentation, weil sie annehmen, dass Nutzer ihre Vorurteile und Kenntnisse teilen. Um dies zu überwinden, bezahlte der Autor echte Nutzer 25 Euro pro Stunde dafür, den README ihres Activity Bot laut vorzulesen, während sie ihren Bildschirm teilten. Dadurch wurden kritische Mängel sichtbar: kapotte Demo-Links, verwirrende Schritte zum Umbenennen von Dateien, unklare technische Begriffe, schlechte Abschnittsreihenfolge und unerklärter Softwarezweck.
Der Autor machte handschriftliche Notizen, aktualisierte den README nach jeder Sitzung und testete anschließend mit neuen Nutzern. Über mehrere Sitzungen zahlten sie insgesamt 150 Euro für ehrliches Feedback. Dieser Prozess zeigte, dass echte Nutzer versteckte Annahmen aufdecken — wie den Bedarf an sudo, Neustartanforderungen und Zitierregeln — die Entwickler oft übersehen. Im Gegensatz zu LLMs bringen echte Menschen Humor, einzigartige Perspektiven und emotionale Signale wie Frustration mit, die darauf hinweisen, wo die Dokumentation versagt.
Der Autor vergleicht dies mit seiner Erfahrung in der technischen Schreibweise für GOV. UK, wo menschliche Überprüfung blumige Prosa in klare, nutzbare Dokumente verwandelte. Obwohl der README nicht perfekt ist, ist er jetzt demonstriert leichter zu folgen.
Die Kernbotschaft: Entwickler sollten Dokumentation mit echten Menschen testen, die laut nachdenken — auch unbezahlt — um blinde Flecken zu finden und die Benutzerfreundlichkeit zu verbessern.
Quelle: Hacker News · Zusammengefasst von HeadlinesBriefing