Warum dokumentieren wir Open Source eigentlich für Menschen, die es nie lesen werden?

    Ich bin gerade dabei, eine README zu schreiben – du kennst das, 47 Absätze Installation, drei Codebeispiele, liebevoll strukturiert – und denke mir: Wer liest das eigentlich wirklich? Oder vielmehr: Wer sollte es lesen, tut es aber nicht, weil die Person längst drei StackOverflow-Antworten kombiniert hat und jetzt einfach hofft, dass es funktioniert. Habt ihr das auch, dass ihr bei Open-Source-Projekten viel Zeit in Dokumentation steckt, die dann hauptsächlich von der Autorin selbst in drei Monaten konsultiert wird, weil sie selbst vergessen hat, wie das alles funktioniert? Wie handhabt ihr das – schreibt ihr für das Ideal-Publikum oder eher für den panischen 3-Uhr-morgens-Version eurer selbst?

    Ninaax3 gell, das ist voll das klassische problem – du schreibst für leute, die NIE existieren werden, und ignorierst gleichzeitig den echten use case: irgendwer (wahrscheinlich du selbst) im halbschlaf um 2 uhr nachts, der grad nicht mehr weiss, ob der api key in die ENV oder in die config.json gehört. Ich hab mal gelesen (ich glaub in irgendeinem essaysammlung über handwerk und software), dass die beste dokumentation eigentlich ein memo an dein zukünftiges ich ist – und alles andere ist bonus. Wenn du für diese panische 3-uhr-version schreibst, ist die dokumentation quasi automatisch auch für anfänger brauchbar, weil du gar nicht erst in die verlockung kommst, zu viel kontext vorauszusetzen. Vielleicht sollte man weniger eine «vollständige» readme anstreben und mehr sowas wie ein entscheidungsbaum: «brauchst du das schnell zum laufen? Hier. Brauchst du erweiterte konfiguration? Da. Willst du migrieren? Dort.» Wie viel zeit steckst du denn aktuell in dokumentation rein, die du dann selbst nie wieder anschaust?

Jetzt mitmachen!

Sie haben noch kein Benutzerkonto auf unserer Seite? Registrieren Sie sich kostenlos und nehmen Sie an unserer Community teil!

Benutzerkonto erstellen Anmelden