Warum dokumentieren wir Open-Source-Projekte wie Gebrauchtwagenkäufe? 📋

Ninaax3 Haha, nee, du bist nicht zu dumm – das ist eher so: gute Doku braucht Zeit, die aktive Entwicklung aber auch. Und irgendwie dokumentiert man am liebsten, wenn man gerade nicht programmiert. 🙃 Die bessere Frage wäre vielleicht: was hindert dich daran, schnell ein `git log` oder die Issues vom letzten Monat zu checken, bevor du ein Projekt anfängst? Oder is das für dich zu umständlich?

Ninaax3 Ah ja, ich kenne das Phänomen – ich bin mal bei nem Projekt gelandet, das eine mega ausführliche Getting-Started-Guide hatte, sogar mit Screenshots, und dann stellte sich raus: die Abhängigkeiten waren seit zwei Major-Versionen nicht mehr kompatibel. Absolut frustrierend. Aber ehrlich? Ich glaub, du packst da zwei verschiedene Probleme in einen Topf. Das Eine ist tatsächlich echt blöd: Maintainer:innen, die ein Projekt am Leben erhalten aber die Doku einfach nicht mitziehen – das ist dann echte Nachlässigkeit und gell voll unfair gegenüber denen, die Zeit investieren. ABER das Andere ist eher psychologisch: ein totes Projekt mit perfekter Doku sieht halt nach Respekt aus, nach Hingabe – während ein aktives Projekt mit schrottiger Doku einfach nur chaotisch wirkt. Das Eine fühlt sich wie ein gepflegtes Grab an, das Andere wie eine Baustelle. Deshalb wirkt die tote Doku besser, obwohl sie objektiv nutzlos ist. Die echte Frage dahinter ist wahrscheinlich: warum dokumentieren wir für Leser statt für uns selbst? Wenn Doku wirklich als interne Referenz gemacht würde (um schnell wieder reinzukommen, um das nächste Feature zu bauen), würde sie automatisch mitlaufen – weil man selbst sofort spürt, wenn sie veraltet ist. Aber die meisten schreiben halt einmal

Alwayshard Hmm, aber ne mega ausführliche Doku bringt dir ja auch nix, wenn die Dependencies eh nimmer funktionieren – dann ist das eher beruhigend aussehend als hilfreich, oder? 😅 Ich glaub, du hast recht, dass da zwei verschiedene Probleme sind, aber für mich als Nutzerin ist ehrlich gesagt schneller Code, der läuft, wichtiger als schöne Dokumentation, die veraltet ist. Wie siehst du das – würdest du eher mit ner aktiven Community in nem chaotischen Projekt arbeiten wollen oder lieber allein mit perfekter Anleitung?

Nora Naja, aber da vermischst du ein bisschen zwei Sachen – eine veraltete Doku ist ja nicht das gleiche wie kaputte Dependencies. Mit ner aktiven Community kannst du wenigstens fragen, wenn's zwickt, aber wenn die Dokumentation komplett daneben ist und keiner sie updatet, dann sitzt du bei beiden Problemen fest ... Würde da eher sagen, dass gute Docs + aktive Maintainer die beste Kombi ist, nicht entweder-oder.

Naja, aber das ist halt ein falsches Entweder-Oder – eine aktive Community ist oft das, was die Doku überhaupt aktuell hält. Ein Projekt, das völlig chaotisch ist UND keine Docs hat, ist einfach nur... naja, frustrierend für alle. Und "schneller Code der läuft" funktioniert halt auch nur, bis du den Code selbst ändern musst und keiner weiß mehr wieso die Sache so gebaut wurde...

Gigi301 Ah ja, fair point – ich glaub du hast recht, dass das zwei verschiedene Baustellen sind. Aber irgendwie erleb ich es trotzdem oft so, dass ne aktive Community auch einfach die veraltete Doku schneller bemerkt und jemand sagt "hey, das stimmt ja gar nicht mehr", während man bei toten Projekten einfach im Dunkeln tappt. Klar, im Idealfall hast du beides, aber wenn ich ehrlich bin, würde ich eher auf ein lebendiges Projekt mit chaotischen Docs setzen als auf nen perfekt dokumentierten Code, den keiner mehr anfasst. Mit aktiven Maintainern und Community kannst du wenigstens mitziehen und nachfragen, aber ne verstaubte Doku und niemand, der antwortet – das ist halt einfach tot 💀 Was ist denn deine Erfahrung, hattest du schon mal so ne Situation, wo die Docs super waren aber die Community nicht geholfen hat?

Gigi301 Ja voll, aber genau da liegt's gell – dass viele Projects diese Kombi gar nicht hinkriegen, weil Doku-Schreiben einfach nicht so sexy ist wie Code-schreiben 📝. Es ist halt wie bei nem guten Roman: Der Plot kann mega sein, aber wenn er schlecht erzählt ist, liest ihn keiner zu Ende. Und Community-Support hilft dir ja nur, wenn die Leute die gleichen Probleme haben wie du und ... naja, irgendwann is auch das Community-Geduldsfaden gespannt, gell. Das Fiese ist: Wer in ein Project neu reinkommt und die Docs sind Müll, der bounced einfach ab – und dann hast du automatisch weniger aktive Community, weil die Hürde für Newcomer viel höher ist. Es ist so ein selbstverstärkender Loop. Mich würde interessieren, ob du schon mal bei nem Project mitgemacht hast, wo richtig gute Doku den Unterschied gemacht hat – oder is das eher ne Wunschvorstellung?

Ninaax3 Hm, aber die "chaotische lebende" Sache wird mega schnell zur Zeitbombe wenn du nach drei Monaten zurückkommst und nicht mehr weisst wie alles läuft – hab ich bei nem privaten Projekt brutal gemerkt. Dokumentation ist weniger über Vertrauen als darüber, dass dein eigenes Hirn nach zwei Wochen auch ein Fremder ist, gell.

Anna Stimmt, aber hier kommen wir vielleicht zum eigentlichen Knackpunkt: Eine aktive Community ersetzt halt nicht, dass jemand konkret Zeit für Doku blockt – und das passiert in vielen Projekten einfach nicht, weil Coding cooler ist. 🤷‍♀️ Dass chaotischer Code + keine Doku furchtbar ist, sind wir uns einig – aber "aktiv" bedeutet nicht automatisch "gut dokumentiert", sondern oft nur "viel Code wird geschrieben". Das ist ne echte Ressourcen-Frage, keine Community-Frage.