Season of Docs ist ein Nachhaltigkeitsprogramm, das vom Open Source Programs Office von Google verwaltet wird. Die Ziele von Season of Docs sind:
- Unterstützung für Open-Source-Projekte zur Lösung von Projektproblemen mit Dokumentation
- Technischen Redakteuren die Möglichkeit geben, Erfahrungen mit Open Source zu sammeln
- Aufmerksamkeit für Open Source, Dokumentation und technisches Schreiben schaffen
- Informationen zu effektiven Messwerten in der Open-Source-Dokumentation erfassen und teilen
Weitere Informationen zu Season of Docs findest du auf der Website des Programms.
Programmübersicht für 2022
So funktioniert Season of Docs
Für Season of Docs bewerben sich Organisationen, indem sie einen Projektvorschlag einreichen. Der Projektvorschlag umfasst:
- Informationen zur Organisation
- Beschreibung des Problems, mit dem das Projekt konfrontiert ist
- Wie das Projekt die Dokumentation zur Lösung des Problems nutzt
- Wie die Effektivität der Dokumentation im Projekt gemessen wird (Messwerte)
- Einen Zeitplan für die Arbeit
- Ein Projektbudget
- Alle zusätzlichen Informationen, z. B. die Erfahrung der Organisation in ähnlichen Programmen oder alles andere, was den Season of Docs-Administratoren helfen würde, ihr Projekt und ihr Problem zu verstehen
Sobald sie in das Programm aufgenommen wurden, stellen die Organisationen ihre eigenen technischen Redakteure direkt ein. Season of Docs verwendet Open Collective, um die Organisationen zu finanzieren, und die Organisationen bezahlen die technischen Redakteure über Open Collective. Projektbudgets und -zahlungen sind transparent. Die Budgets sind in den Projektvorschlägen der Organisationen enthalten, die auf der Website von Season of Docs verfügbar sind. Zahlungen sind im Open Collective-Konto von Season of Docs sichtbar.
Organisationen gelten als erfolgreich, wenn sie ihren Fallstudienbericht einreichen. Außerdem werden die Organisationen gebeten, während des Programms monatliche Bewertungen und im Jahr nach Abschluss des Programms drei vierteljährliche Folgeumfragen durchzuführen.
Highlights 2022
„Nach der Veröffentlichung des neuen Dokuments haben sich die täglichen Besuche auf Casbin und Casdoor fast verdoppelt und die Absprungraten sind um etwa 30 % gesunken.“ – Casbin
„Ein erfreuliches Ergebnis dieses Projekts war, dass [unsere technischen Redakteure] in Führungspositionen in unserer Community aufgestiegen sind. Beide Mitwirkenden leiten jetzt Arbeitsgruppen und Community-Treffen und tragen zum Design und zur Pflege unserer Projekte bei.“ – moja-global
„[GSoD] hat uns dabei geholfen, zwei talentierte technische Redakteure zu finden, was in einer normalen Umgebung sehr schwierig ist. Sie sind weiterhin aktive Open-Source-Mitarbeiter bei OpenMined und wir haben sehr gute Erfahrungen mit ihnen gemacht.“ – OpenMined
„Außerdem ist das neue Handbuch für Einsteiger in die computergestützte Massenspektrometrie viel einfacher. Zur Veranschaulichung: Das CZI-Stipendium umfasst auch Stipendien für benachteiligte Personen. Einige Stipendiaten haben das neue OpenMS-Handbuch genutzt, um ihre sechswöchige Praktikumszeit zu beginnen, und haben das neue Handbuch positiv bewertet.“ – OpenMS
Zusammenfassungsdaten für 2022
2022 wurden im Rahmen des Season of Docs-Programms 31 Projekte aus 67 Anträgen angenommen und 30 Projekte haben das Programm erfolgreich abgeschlossen. Von den 31 akzeptierten Organisationen hatten 17 bereits in der Vergangenheit einen Antrag gestellt.
Für die 31 akzeptierten Projekte wurden 58 Technische Redakteure eingestellt. Mehr als 190 Technische Redakteure haben ihr Interesse an der Teilnahme am Programm bekundet, indem sie ihre Kontaktdaten und Links zu ihren Portfolios in das GitHub-Repository von Season of Docs eingefügt haben.
Für das Programm 2022 gilt Folgendes:
- 100% der Organisationen waren mit dem Bewerbungsprozess zufrieden.
- 100% der Organisationen waren mit der Dokumentation/den Inhalten der Programmwebsite zufrieden.
- 93% der Organisationen waren mit dem Programm zufrieden
- 90% der Organisationen waren der Meinung, dass ihr Dokumentationsprojekt erfolgreich war
Informationen zu den Organisationen
Die an der Season of Docs 2022 teilnehmenden Organisationen repräsentierten eine Vielzahl von Open-Source-Projekten. Die Kohorte 2022 umfasste:
- Entwicklungstools wie AsyncAPI und SpyderIDE
- Programmiersprachen und ‑frameworks wie Julia, LFortran, R und p5.js
- Wissenschaftliche Projekte wie CERN-HSF und SymPy
- Endnutzeranwendungen wie Mautic, Open Food Facts, Talawa und Ushahidi
- Hardware- und Roboterprojekte wie ExpressLRS und Open-RMF
- Datenprojekte wie GeomScale, GeomStats, OpenMined und Weaviate
- Cloud- und Infrastrukturprojekte wie cert-manager, NimbleEdge und Cilium
Wir haben keine Metadaten zu den Projekten erhoben, z. B. Gründungsdatum, geografische Verteilung der Mitwirkenden, Anzahl der Mitwirkenden oder Größe der Nutzerbasis.
Wir haben die Projekte jedoch gebeten, anzugeben, welche Open-Source-Lizenz sie verwendet haben.
Die Dokumentationsprojekte
Probleme mit der Dokumentation
Zu den wichtigsten Problemen, die Organisationen mit der Dokumentation im Programm 2022 lösen wollten, gehörten:
Hinweis: Organisationen können mehrere Dokumentationsprobleme melden. Weitere Informationen finden Sie auf der Ergebnisseite von Season of Docs 2022, auf der es Links zu den ursprünglichen Projektvorschlägen und vollständigen Fallstudien für jede Organisation gibt.
Erstellte Dokumentationstypen
In den Fallstudien von 2022 wurde am häufigsten die Anleitung als Dokumentationstyp genannt.
Weitere in den Fallstudien erwähnte Dokumentationstypen:
- Kurzanleitung
- Glossar
- FAQ
- Wissensdatenbank
- Komponenten
- Blog-/Social-Media-Inhalte
- Leitfaden für Betreuer
Einige dieser Kategorien sind unscharf und ein einzelnes Dokumentationsprojekt kann mehrere Dokumentationstypen oder -funktionen enthalten.
Weitere Informationen finden Sie auf der Ergebnisseite von Season of Docs 2022. Dort finden Sie Links zu den ursprünglichen Projektvorschlägen und vollständigen Fallstudien für jede Organisation.
Budgets
Der durchschnittliche Budgetantrag betrug 11.679 $und der Median 12.150 $. Fünf Organisationen haben den höchsten verfügbaren Zuschuss in Höhe von 15.000 $ beantragt und erhalten, drei den niedrigsten (zwischen 5.000 und 7.000 $).
Messdaten
In ihren Fallstudien haben sie die Messwerte beschrieben, mit denen sie den Erfolg ihrer Dokumentationsprojekte gemessen haben.
Die am häufigsten vorgeschlagenen Messwerte waren:
Weitere vorgeschlagene Messwerte:
- Mehr Pull-Requests/Beiträge zur Dokumentation
- Direkteres Feedback auf Dokumentationsseiten
- Auf der Seite verbrachte Zeit
- Gemeldete Probleme (als Proxy für die Nutzung)
- Teilnehmer an Foren
- Anzahl der Partner/Freiwilligen/Integrationen
- Reduzierte Absprungrate
- Mehr Aufmerksamkeit in der Community.
Aufgrund des kurzen Zeitraums zwischen dem Abschluss der technischen Schreibprojekte und dem Einreichen der Fallstudien konnten die meisten Teilnehmer des Jahrgangs 2022 zum Zeitpunkt der Einreichung ihrer Fallstudien nicht genügend Daten erheben, um festzustellen, ob ihre ursprünglichen Messwerte erreicht wurden.
Sobald wir Antworten auf die Folgeumfragen 2023 erhalten, aktualisieren wir diesen Bericht und fügen Informationen hinzu, welche Projekte ihre Messwerte erreicht oder überarbeitet haben.
Weitere Informationen finden Sie auf der Ergebnisseite von Season of Docs 2022, auf der es Links zu den ursprünglichen Projektvorschlägen und vollständigen Fallstudien für jede Organisation gibt.
Zusammenarbeit mit technischen Redakteuren
Im Rahmen des Season of Docs-Programms werden die Projekte gebeten, technische Redakteure direkt zu rekrutieren, zu interviewen, einzustellen und zu bezahlen. Technische Redakteure können sich in unserem GitHub-Repository in das von Season of Docs geführte Verzeichnis aufnehmen lassen. Die Mitarbeiter von Season of Docs prüfen oder empfehlen sie jedoch nicht.
Best Practices für die Einstellung von technischen Redakteuren für Open-Source-Projekte
Die Projekte wurden gebeten, ihre Best Practices für die Rekrutierung, Einstellung und Zusammenarbeit mit technischen Redakteuren zu teilen. Die wichtigsten Empfehlungen waren:
Personalvermittlung
- Weniger Kandidaten interviewen und eine Live-Übungsrunde statt nur Lebensläufe durchgehen
- Schriftliche und mündliche Kommunikationskompetenzen vor Kenntnissen in der Sprache oder den Tools Ihres Projekts stellen
- Stellen Sie direkte Fragen dazu, wie der Technische Redakteur das für die Arbeit an Ihrem Projekt erforderliche Fachwissen erwerben wird.
- Jemand, der sich für den Zweck Ihres Projekts begeistert und die wichtigsten Open-Source-Werte teilt, bleibt mit größerer Wahrscheinlichkeit während des gesamten Projekts motiviert.
- Seien Sie offen für Bewerber aus aller Welt, da eine Vielfalt an Perspektiven und Hintergründen Ihrem Projekt helfen wird. Beachten Sie jedoch, dass es viel zusätzliche Mühe erfordern kann, eine gute Kommunikation aufrechtzuerhalten, wenn Autoren und Mentoren in zu vielen Zeitzonen mit unterschiedlichen Zeitplänen arbeiten.
Rekrutierung
- Verwenden Sie einen Vertrag, in dem die zu erbringenden Leistungen, Zahlungspläne und spezifische Zeitverpflichtungen klar festgelegt sind.
- Wenn Ihr Projekt viele Unbekannte aufweist, sollten Sie einen Meilenstein für die Recherche oder Forschung angeben, der von der Erstellung der Dokumentation getrennt ist.
Koordination und Kommunikation
- Behalten Sie ein Sitzungsprotokoll mit den getroffenen Entscheidungen, damit alle am Projekt Beteiligten den Kontext und die nächsten Schritte besser nachvollziehen können.
- Geben Sie klar an, welche Art der Kommunikation erwartet wird und wie oft, z. B. wöchentliche Anrufe, tägliche E-Mails oder Statusaktualisierungen in einem Chatkanal.
- Seien Sie reaktionsschnell und geben Sie klares Feedback, das nicht nur das „Was“, sondern auch das „Warum“ enthält.
- Stellen Sie Ihre technischen Redakteure der breiteren Community vor, um ihnen Kontext zu bieten und ihre Arbeit zu präsentieren
Prozesse und Tools
- Einen Dokumentationsprozess schaffen, der über das Season of Docs-Programm hinausgeht und an dem die gesamte Community mitwirken kann
- Die Überprüfung der Dokumentation dauert mindestens genauso lange und ist genauso intensiv wie die Codeüberprüfung. Planen Sie also genügend Zeit dafür ein.
Einige Empfehlungen wurden zugunsten der Verständlichkeit bearbeitet und gekürzt.
Wie auch im Programm 2021 haben sich die meisten technischen Redakteure in der Season of Docs 2022 direkt bei den Organisationen beworben, mit denen sie zusammengearbeitet haben.
Häufige Probleme bei der Zusammenarbeit mit technischen Redakteuren
Im Programm 2022 wurden weniger Probleme bei der Zusammenarbeit mit technischen Redakteuren gemeldet. Das größte Problem war, dass technische Redakteure das Programm aufgrund von Krankheit, einer Vollzeitbeschäftigung oder aufgrund der zeitlichen Anforderungen nicht abschließen konnten.
Bei einem Projekt wurde angegeben, dass die Dokumentation von der Arbeit abhing, die im Rahmen des Google Summer of Code geleistet wurde, und dass diese Abhängigkeiten schwierig zu verwalten waren. Bei einem anderen Projekt kam es zu Schwierigkeiten, als die Hardware, die der technische Redakteur dokumentieren musste, vom Verteidigungsministerium des Landes beschlagnahmt und nicht importiert werden konnte.
Folgeumfragen
Im Mai, August und November 2023 werden den Teilnehmern von 2022 drei Folgeumfragen gesendet. Wir aktualisieren diesen Abschnitt mit den Ergebnissen, sobald sie vorliegen.
Zukünftige Fragen
Wie immer gilt: Je mehr wir über Open-Source-Dokumentation erfahren, desto mehr möchten wir lernen.
In zukünftigen Saisons möchten wir:
- Mehr Projektmetadaten erfassen, um nach Korrelationen zwischen Projektalter, Communitygröße oder Sprache und Dokumentationsanforderungen zu suchen
- Dokumentationsprojekte analysieren, um festzustellen, ob sie in freigegebene Vorlagen verallgemeinert werden können
- Eine Bewertungsskala für Interviews mit technischen Redakteuren in Open-Source-Projekten entwickeln
Es gibt viele Fragen, die wir gerne untersuchen würden. Wir möchten aber auch die Zeit der Open-Source-Projektadministratoren und -Betreuer respektieren, die an der Season of Docs teilnehmen. Die oberste Priorität des Programms besteht darin, Projekte bei der Lösung ihrer Dokumentationsprobleme zu unterstützen.