Season of Docs ist ein Nachhaltigkeitsprogramm, das vom Google Open Source Programs Office verwaltet wird. Die Ziele von Season of Docs sind:
- Unterstützung für Open-Source-Projekte, um Projektprobleme mit Dokumentation zu lösen
- Möglichkeiten für technische Redakteure, Erfahrungen mit Open Source zu sammeln
- Sensibilisierung für Open Source, Dokumentation und technisches Schreiben
- Erfassen und Weitergeben von Informationen zu effektiven Messwerten in der Open-Source-Dokumentation
Weitere Informationen zu Season of Docs finden Sie auf der Programmwebsite.
Programmübersicht 2022
Funktionsweise von Season of Docs
Bei Season of Docs bewerben sich Organisationen mit einem Projektvorschlag. Der Projektvorschlag umfasst:
- Informationen zur Organisation
- Eine Beschreibung des Problems, mit dem das Projekt konfrontiert ist
- Wie das Projekt Dokumentation verwenden wird, um das Problem zu lösen
- Wie das Projekt die Effektivität der Dokumentation messen wird (Messwerte)
- Ein Zeitplan für die Arbeit
- Ein Projektbudget
- Alle zusätzlichen Informationen, z. B. die Erfahrung der Organisation mit ähnlichen Programmen oder alles andere, was den Administratoren von Season of Docs helfen würde, das Projekt und das Problem zu verstehen
Nach der Aufnahme in das Programm rekrutieren und beauftragen Organisationen ihre eigenen technischen Redakteure direkt. 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. Budgets sind in den Projektvorschlägen der Organisationen enthalten, die auf der Season of Docs-Website verfügbar sind, und Zahlungen sind im Open Collective-Konto von Season of Docs sichtbar.
Organisationen haben das Programm erfolgreich abgeschlossen, wenn sie ihren Fallstudienbericht einreichen. Organisationen werden außerdem gebeten, während des Programms monatliche Bewertungen und im Jahr nach Abschluss des Programms drei vierteljährliche Follow-up-Umfragen durchzuführen.
Highlights 2022
„Nach der Veröffentlichung des neuen Dokuments hat sich die Anzahl der täglichen Besuche auf Casbin und Casdoor fast verdoppelt und die Absprungraten sind um etwa 30 % gesunken.“ – Casbin
„Ein erfreuliches Ergebnis dieses Projekts war es, zu sehen, wie sich [unsere technischen Redakteure] zu Führungskräften in unserer Community entwickelt haben. Beide Mitwirkenden leiten jetzt Arbeitsgruppen- und Community-Meetings und tragen zum Design und zur Wartung unserer Projekte bei.“ – moja-global
„[GSoD] hat uns geholfen, zwei talentierte technische Redakteure zu rekrutieren, was in einer regulären Konfiguration sehr schwierig ist. Sie sind weiterhin aktive OS-Mitwirkende bei OpenMined und wir haben sehr gut mit ihnen zusammengearbeitet.“ – OpenMined
„Außerdem ist das neue Handbuch für Neulinge in der computergestützten Massenspektrometrie viel einfacher zu verstehen. Um dies zu veranschaulichen: Das CZI-Stipendium bietet auch Stipendien für historisch benachteiligte Personen und einige Stipendiaten haben das neue OpenMS-Handbuch genutzt, um ihr sechswöchiges Praktikum zu beginnen, und haben positive Bewertungen des neuen Handbuchs abgegeben.“ – OpenMS
Zusammenfassungsdaten 2022
Im Jahr 2022 wurden im Rahmen des Season of Docs-Programms 31 Projekte aus 67 Bewerbungen akzeptiert und 30 Projekte haben das Programm erfolgreich abgeschlossen. Von den 31 akzeptierten Organisationen waren 17 Organisationen wiederholte Bewerber.
Die 31 akzeptierten Projekte haben 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 im Season of Docs GitHub-Repository hinzugefügt haben.
Für das Programm 2022:
- 100% der Organisationen hatten eine positive Erfahrung mit dem Bewerbungsprozess
- 100% der Organisationen hatten eine positive Erfahrung mit der Dokumentation/den Inhalten der Programmwebsite
- 93% der Organisationen hatten eine positive Erfahrung mit dem Programm
- 90% der Organisationen waren der Meinung, dass ihr Dokumentationsprojekt erfolgreich war
Über die Organisationen
Die an Season of Docs 2022 teilnehmenden Organisationen repräsentierten eine Vielzahl von Open-Source-Projekten. Die Gruppe von 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 Robotikprojekte 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 gebeten, anzugeben, welche Open-Source-Lizenz sie verwenden.
Über die Dokumentationsprojekte
Probleme mit der Dokumentation
Zu den größten Problemen, die Organisationen im Rahmen des Programms 2022 mit Dokumentation lösen wollten, gehörten:
Organisationen konnten mehrere Probleme mit der Dokumentation melden. Weitere Informationen finden Sie auf der Ergebnisseite von Season of Docs 2022 results page, auf der die ursprünglichen Projektvorschläge und vollständigen Fallstudien für jede Organisation verlinkt sind.
Erstellte Dokumentationstypen
Die Anleitungsdokumentation wurde in den Fallstudien von 2022 am häufigsten erwähnt.
Weitere in Fallstudien erwähnte Dokumentationstypen:
- Kurzanleitung
- Glossar
- FAQ
- KnowledgeBase
- 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 results page, auf der die ursprünglichen Projektvorschläge und vollständigen Fallstudien für jede Organisation verlinkt sind.
Budgets
Die durchschnittliche Budgetanfrage betrug 11.679 $ und der Median lag bei 12.150 $. Fünf Organisationen haben das höchste verfügbare Stipendium (15.000 $) beantragt und erhalten, drei haben das niedrigste beantragt (zwischen 5.000 $ und 7.000 $).
Messwerte
In ihren Fallstudien haben die Projekte die Messwerte beschrieben, mit denen sie den Erfolg ihrer Dokumentationsprojekte messen.
Die am häufigsten vorgeschlagenen Messwerte waren:
Weitere vorgeschlagene Messwerte:
- Mehr Pull-Anfragen/Beiträge zur Dokumentation
- Mehr direktes Feedback auf Dokumentationsseiten
- Auf der Seite verbrachte Zeit
- Gemeldete Probleme (als Proxy für die Nutzung)
- Teilnehmer in Foren
- Anzahl der Partner/Freiwilligen/Integrationen
- Geringere Absprungrate
- Höhere Bekanntheit in der Community
Aufgrund des kurzen Zeitraums zwischen dem Abschluss der technischen Schreibprojekte und der Einreichung der Fallstudien konnten die meisten Teilnehmer des Programms 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 Follow-up-Umfragen im Jahr 2023 erhalten, werden wir diesen Bericht aktualisieren und Informationen dazu hinzufügen, welche Projekte ihre Messwerte erreicht oder überarbeitet haben.
Weitere Informationen finden Sie auf der Ergebnisseite von Season of Docs 2022 results page, auf der die ursprünglichen Projektvorschläge und vollständigen Fallstudien für jede Organisation verlinkt sind.
Zusammenarbeit mit technischen Redakteuren
Im Rahmen des Season of Docs-Programms müssen Projekte technische Redakteure direkt rekrutieren, interviewen, einstellen und bezahlen. Technische Redakteure können sich selbst in das von Season of Docs in unserem GitHub-Repository geführte Verzeichnis eintragen, aber die Mitarbeiter von Season of Docs überprüfen oder empfehlen keine technischen Redakteure.
Best Practices für die Einstellung technischer Redakteure 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:
Rekrutierung
- Weniger Kandidaten interviewen und eine Live-Übungssitzung durchführen, anstatt nur Lebensläufe zu prüfen
- Schriftliche und mündliche Kommunikationsfähigkeiten sind wichtiger als Kenntnisse der Sprache oder der Tools des Projekts
- Direkte Fragen dazu stellen, wie sich der technische Redakteur das für die Arbeit an Ihrem Projekt erforderliche Fachwissen aneignen wird
- Eine Person, die sich für die Mission Ihres Projekts begeistert und die wichtigsten Open-Source-Werte teilt, bleibt eher während des gesamten Projekts motiviert
- Offen für Bewerber aus aller Welt sein, da eine Vielfalt an Perspektiven und Hintergründen Ihrem Projekt helfen kann. Sie sollten jedoch bedenken, dass es viel zusätzlichen Aufwand erfordern kann, eine gute Kommunikation aufrechtzuerhalten, wenn Autoren und Mentoren in zu vielen unterschiedlichen Zeitzonen arbeiten
Einstellung
- Einen Vertrag verwenden, in dem die Liefergegenstände, Zahlungspläne und spezifischen Zeitverpflichtungen klar festgelegt sind
- Wenn Ihr Projekt viele Unbekannte enthält, einen Meilenstein für die Recherche oder Recherche getrennt von der Erstellung der Dokumentation einfügen
Koordination und Kommunikation
- Ein Besprechungsprotokoll mit den Entscheidungen führen, damit alle, die am Projekt arbeiten, den Kontext und die nächsten Schritte verstehen können
- Klar angeben, welche Kommunikation erwartet wird und wie oft, z. B. wöchentliche Anrufe, tägliche E-Mails oder Statusaktualisierungen in einem Chatkanal
- Reagieren und klares Feedback geben, das auch die Gründe für das Feedback enthält und nicht nur das „Was“
- Technische Redakteure mit der breiteren Community in Kontakt bringen, um ihnen Kontext zu geben und ihre Arbeit zu präsentieren
Prozesse und Tools
- Einen Dokumentationsprozess erstellen, der über das Season of Docs-Programm hinausgeht und zu dem die gesamte Community beitragen kann
- Die Überprüfung der Dokumentation dauert mindestens so lange und ist genauso intensiv wie die Codeüberprüfung. Planen Sie dafür ausreichend Zeit ein.
Einige Empfehlungen wurden zur besseren Verständlichkeit bearbeitet und gekürzt.
Wie im Programm 2021 haben sich die meisten technischen Redakteure bei 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 haben weniger Projekte Probleme bei der Zusammenarbeit mit ihren technischen Redakteuren gemeldet. Das größte Problem war, dass technische Redakteure das Programm aufgrund von Krankheit, einer Vollzeitstelle oder mangelnder Zeit nicht abschließen konnten.
Ein Projekt berichtete, dass sein Dokumentationsprojekt von Arbeiten abhängig war, die im Rahmen von Google Summer of Code durchgeführt wurden, und dass diese Abhängigkeiten schwer zu verwalten waren. Ein anderes Projekt hatte Schwierigkeiten, als die Hardware, die der technische Redakteur dokumentieren musste, vom Verteidigungsministerium im Land des Autors beschlagnahmt wurde und nicht importiert werden konnte.
Follow-up-Umfragen
Im Mai, August und November 2023 werden drei Follow-up-Umfragen an die Teilnehmer des Programms 2022 gesendet. Wir werden diesen Abschnitt mit den Ergebnissen aktualisieren, sobald sie eingehen.
Zukünftige Fragen
Je mehr wir über die Dokumentation in Open Source erfahren, desto mehr möchten wir lernen.
In zukünftigen Staffeln möchten wir:
- Weitere Projektmetadaten erheben, um Korrelationen zwischen Projektalter, Community-Größe oder Sprache und Dokumentationsanforderungen zu finden
- Dokumentationsprojekte analysieren, um zu sehen, ob sie in gemeinsam nutzbare Vorlagen umgewandelt werden können
- Eine Bewertungsrichtlinie für die Befragung technischer Redakteure in Open-Source-Projekten entwickeln
Es gibt viele Fragen, die wir untersuchen möchten, aber wir möchten auch die Zeit der Open-Source-Projektadministratoren und -Betreuer respektieren, die an Season of Docs teilnehmen. Die oberste Priorität des Programms ist es, Projekte bei der Lösung ihrer Probleme mit der Dokumentation zu unterstützen.