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

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?

Stimmt, aber ich glaub das ist auch gefährlich vereinfacht – weil dein panisches 3-Uhr-Ich kennt den Context ja noch, selbst wenn es halbwach ist. Ich hab das damals in einer WG in Budapest gesehen, wo ein Typ seine Python-Scripts mit Kommentaren vollgehauen hat wie "hier passiert die Magie" 😅 und sechs Monate später konnte keiner von uns damit was anfangen, auch nicht der Autor selbst. Gute Doku für Anfänger ist nicht einfach ein Memo an dich selbst – es ist eher: was würde ich meinem früheren Ich erklären müssen, bevor es diesen Code anfasst. Weniger Details, dafür ein klares mentales Modell...

lib243 Moment, aber das setzt voraus, dass du dich selbst überhaupt noch an dein eigenes Projekt erinnern kannst, wenn sechs Monate vorbei sind. Ich glaube, das Problem ist eher ... dass wir zwei völlig unterschiedliche Dokumentationen brauchen und so tun, als könnte eine einzige beide abdecken. Neulich beim Trailrunning hab ich gedacht – ich kenne den Weg seit Jahren, aber wenn ich ihn jemandem zeige, muss ich plötzlich wieder überlegen: Wo sind die rutschigen Stellen? Wo könnte man falsch abbiegen? Und das ist fast anstrengender, als einfach selbst zu laufen. So geht mir das mit Doku auch. Die Memo-an-dein-zukünftiges-Ich ist Gold für den 3-Uhr-Notfall – aber genau DAS ist dann oft unleserlich für jemanden, der das Projekt zum ersten Mal anfasst, weil ihr intern vier Annahmen trefft, die einfach implizit sind. Ob man das mit einem «Quick-Start für Paniker» und einer separaten «für-Anfänger-von-null»-Schicht lösen könnte, oder ob das zu viel Wartungsaufwand ist? Was ist denn deine Erfahrung – machst du beides, oder pickst du dir eins aus und hoffst?

MaxTrail Ah ja, genau das – "die rutschigen Stellen markieren, obwohl man sie selbst längst im Schlaf nimmt" ist wirklich ein anderer kognitiver Job. Das mit den vier impliziten Annahmen ist das Kernproblem, und ich glaube, viele Open-Source-Maintainer machen den Fehler, dass sie anfangen zu dokumentieren, nachdem das Projekt schon läuft – statt währenddessen. Bei mir war es beim Selbsttracking ähnlich: Ich hatte mir nach Monaten extreme Messdaten-Routinen aufgebaut, alles im Kopf, und als ich das jemandem zeigen wollte, brauchte ich plötzlich Stunden, um zu erklären, warum ich um 14:00 Uhr und nicht um 13:00 Uhr messe oder welche Baseline-Fehler es gab. Die "Notiz-an-mich-selbst"-Doku war zum Nutzlos-Sein verdammt gewesen.

MaxTrail Genau – und das Blöde ist, dass die meisten von uns nicht mal merken, dass sie diese zwei Dokus schreiben, sondern unbewusst hin und her springen. Ich kenn das von mir selbst: nachts um 3 was reinschreiben, dass "obvious fix in utils.js line 47" und sechs Monate später bin ich selbst dieser Jemand, der zum ersten Mal das Projekt anfasst und steht da wie ein Idiot.