Aktuelle Phase:
Dokumentationsentwicklung. Siehe Zeitachse.
Season of Docs ist ein Nachhaltigkeitsprogramm, das vom Google Open Source Programs Office verwaltet wird. Mit „Season of Docs“ sollen folgende Ziele erreicht werden:
- Unterstützung für Open-Source-Projekte bereitstellen, um Projektprobleme durch Dokumentation zu lösen
- Technischen Redakteuren die Möglichkeit geben, Erfahrungen mit Open Source zu sammeln
- Auf Open Source, Dokumentation und technisches Schreiben sensibilisieren
- Informationen zu effektiven Messwerten in der Open-Source-Dokumentation erheben und teilen
Weitere Informationen zur Staffel von Google Docs finden Sie auf der Website des Programms.
Programmübersicht 2022
So funktioniert die Staffel von Google Docs
In Season of Docs bewerben sich Organisationen, indem sie einen Projektvorschlag einreichen. Der Projektvorschlag umfasst:
- Informationen zur Organisation
- Eine Beschreibung des Problems, mit dem das Projekt konfrontiert ist
- Wie das Projekt die Dokumentation zur Lösung des Problems nutzt
- Wie das Projekt die Wirksamkeit seiner Dokumentation misst (Metriken)
- Einen Zeitplan für die Arbeit
- Ein Projektbudget
- Zusätzliche Informationen, etwa zu den Erfahrungen der Organisation mit ähnlichen Programmen oder sonstige Informationen, die den Administratoren von "Season of Docs" helfen könnten, ihr Projekt und ihr Problem zu verstehen
Nach der Aufnahme in das Programm rekrutieren und engagieren Unternehmen ihre eigenen technischen Redakteure direkt. Season of Docs nutzt Open Collective, um die Organisationen zu finanzieren, und die technischen Redakteure werden über Open Collective bezahlt. Projektbudgets und -zahlungen sind transparent. Budgets sind in den Projektvorschlägen der Organisation enthalten, die auf der Saison of Docs-Website verfügbar sind, und Zahlungen sind im Konto Season of Docs Open Collective sichtbar.
Organisationen gelten als erfolgreich abgeschlossen, wenn sie ihren Fallstudienbericht einreichen. Die Organisationen werden außerdem aufgefordert, 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 bei Casbin und Casdoor fast verdoppelt und die Absprungraten sanken um etwa 30%.“ –Casbin
„Ein erfreuliches Ergebnis dieses Projekts ist es, zu beobachten, wie [unsere technischen Redakteure] sich zu Führungspositionen in unserer Community entwickelt haben. Beide Personen leiten inzwischen Arbeitsgruppen und Community-Meetings und leisten einen Beitrag zur Gestaltung und Betreuung unserer Projekte.“ —moja-global
„Mit [GSoD] haben wir zwei talentierte technische Redakteure rekrutiert, was in einer gewöhnlichen Situation sehr schwierig ist, die weiterhin aktiv zum Betriebssystem von OpenMined beitragen und mit denen wir eine sehr gute Arbeitserfahrung hatten.“ – OpenMined
„Außerdem ist das neue Handbuch für Anfänger im Bereich der computergestützten Massenspektrometrie viel einfacher. Zur Veranschaulichung: Die Förderung der CZI gewährt auch Stipendien für historisch benachteiligte Personen. Einige Teilnehmer haben das neue OpenMS-Handbuch genutzt, um ihren sechswöchigen Praktikumszeitraum zu beginnen, und haben positive Bewertungen für das neue Handbuch abgegeben.“ – OpenMS
Zusammenfassende Daten für 2022
Im Jahr 2022 wurden 31 Projekte aus 67 Bewerbungen für die „Season of Docs“-Bewerbung angenommen, wobei 30 Projekte erfolgreich abgeschlossen wurden. 17 der 31 akzeptierten Organisationen haben sich wiederholt beworben.
Für die 31 akzeptierten Projekte wurden 58 technische Autoren eingestellt. Mehr als 190 technische Autoren gaben ihr Interesse an der Teilnahme am Programm an, indem sie ihre Kontaktinformationen und Links zu ihren Portfolios im GitHub-Repository „Season of Docs“ hinzufügten.
Für das Programm 2022 gilt:
- 100% der Organisationen hatten positive Erfahrungen mit dem Bewerbungsprozess
- 100% der Organisationen hatten positive Erfahrungen mit der Dokumentation/den Inhalten der Programmwebsite
- 93% der Unternehmen hatten positive Erfahrungen mit dem Programm
- 90% der Unternehmen waren der Meinung, dass ihr Dokumentationsprojekt erfolgreich war.
Über die Organisationen
Die Organisationen, die an der „Season of Docs“ 2022 teilgenommen haben, vertreten eine Vielzahl von Open-Source-Projekten. Die Kohorte für 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 Projekte gebeten, anzugeben, welche Open-Source-Lizenz sie verwendet haben.
Dokumentationsprojekte
Dokumentationsprobleme
Zu den häufigsten Problemen, die Unternehmen im Rahmen des Programms für 2022 mit der Dokumentation lösen wollten, waren:
Beachten Sie, dass Organisationen mehrere Dokumentationsprobleme melden können. Weitere Informationen finden Sie auf der Ergebnisseite „Season of Docs 2022“, die Links zu den ursprünglichen Projektvorschlägen und vollständigen Fallstudien für jede Organisation enthält.
Erstellte Dokumentationstypen
Die Dokumentation mit Anleitungen war in den Fallstudien aus dem Jahr 2022 der am häufigsten genannte Dokumentationstyp.
Weitere in Fallstudien erwähnte Dokumentationsarten:
- Kurzanleitung
- Glossar
- Häufig gestellte Fragen
- Wissensdatenbank
- Komponenten
- Bloginhalte/Inhalte in sozialen Medien
- Leitfaden für Administratoren
Einige dieser Kategorien sind ungenau und ein einzelnes Dokumentationsprojekt kann mehrere Dokumentationstypen oder Funktionen enthalten.
Weitere Informationen finden Sie auf der Ergebnisseite „Season of Docs 2022“, die Links zu den ursprünglichen Projektvorschlägen und vollständigen Fallstudien für jede Organisation enthält.
Budgets
Die durchschnittliche Budgetanforderung betrug 11.679 $und der Medianwert 12.150 $. Fünf Organisationen haben den höchsten verfügbaren Zuschuss (15.000 $) beantragt und drei erhalten den niedrigsten Preis (zwischen 5.000 bis 7.000 $).
Messwerte
Die Projekte haben in ihren Fallstudien die Metriken beschrieben, mit denen sie den Erfolg ihrer Dokumentationsprojekte gemessen haben.
Die am häufigsten vorgeschlagenen Messwerte waren:
Weitere vorgeschlagene Messwerte:
- Weitere Pull-Anfragen/-Beiträge zur Dokumentation
- Direkteres Feedback zu Dokumentationsseiten
- Auf der Seite verbrachte Zeit
- Aufgetretene Probleme (als Proxy für die Verwendung)
- Teilnehmer in Foren
- Anzahl der Partner/Freiwilligen/Einbindungen
- Geringere Absprungrate
- Gesteigertes Bewusstsein in der Community
Aufgrund der kurzen Zeitspanne zwischen dem Abschluss der Projekte zur technischen Erstellung und dem Einreichen der Fallstudien konnten die meisten Kohorten von 2022 zum Zeitpunkt der Einreichung der Fallstudien nicht genügend Daten sammeln, um festzustellen, ob die ursprünglichen Metriken erreicht wurden oder nicht.
Sobald wir 2023 Antworten auf die nachfolgenden Umfragen erhalten, wird dieser Bericht mit Informationen darüber aktualisiert, welche Projekte ihre Metriken erreicht oder ihre Metriken überarbeitet haben.
Weitere Informationen finden Sie auf der Ergebnisseite „Season of Docs 2022“, die Links zu den ursprünglichen Projektvorschlägen und vollständigen Fallstudien für jede Organisation enthält.
Mit technischen Redakteuren zusammenarbeiten
Im Rahmen des Programms „Season of Docs“ werden technische Redakteure von Projekten rekrutiert, befragt, eingestellt und bezahlt. Technische Autoren können sich selbst in das Verzeichnis von Season of Docs in unserem GitHub-Repository eintragen. Mitarbeiter von Season of Docs empfehlen technische Redakteure jedoch nicht.
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:
Personalvermittlung
- Gespräche mit weniger Bewerbern und Live-Übungsrunden, anstatt nur die Lebensläufe durchzusehen
- Die schriftliche und mündliche Kommunikationsfähigkeit ist wichtiger als die Kompetenz in der Sprache oder den Tools Ihres Projekts.
- Direkte Fragen dazu stellen, wie sich die technische Redaktion das für die Arbeit mit Ihrem Projekt erforderliche Domänenwissen aneignen wird
- Personen, die sich für die Mission Ihres Projekts begeistern und die zentralen Open-Source-Werte teilen, bleiben mit größerer Wahrscheinlichkeit während des gesamten Projekts motiviert.
- Seien Sie offen für Bewerber aus der ganzen Welt, da eine Vielzahl von Standpunkten und Hintergründen Ihrem Projekt helfen wird. Bedenken Sie jedoch, dass Autoren und Mentoren in zu vielen gegensätzlichen Zeitzonen viel zusätzlichen Aufwand erfordern können, um eine gute Kommunikation aufrechtzuerhalten.
Wir suchen dich!
- Einen Vertrag verwenden, in dem Leistungen, Zahlungspläne und bestimmte Zeitverpflichtungen klar dargelegt werden
- Wenn Ihr Projekt viele Unbekannte hat, fügen Sie neben der Dokumentationserstellung einen Meilenstein für die Entdeckung oder Forschung hinzu
Koordination und Kommunikation
- Entscheidungen in einem Besprechungsprotokoll festhalten, damit alle, die an dem Projekt arbeiten, den Kontext und die nächsten Schritte leichter verstehen
- Machen Sie klar, welche Kommunikation wie oft erwartet wird, z. B. wöchentliche Anrufe, tägliche E-Mails oder Statusupdates in einem Chatkanal.
- Reagieren Sie auf Ihre Antwort und geben Sie klares Feedback, das auch „Warum“ und nicht nur „Was“ enthält.
- Vernetzen Sie Ihre technischen Redakteure mit einer breiteren Community, um mehr Kontext zu bieten und ihre Arbeit sozialer zu gestalten
Prozesse und Tools
- Erstellen Sie einen Dokumentationsprozess, der auch über die Saison von Google Docs hinausgeht und an dem die gesamte Community einen Beitrag leisten kann.
- Die Dokumentation dauert mindestens so lange und ist genauso intensiv wie die Codeüberprüfung. Planen Sie dafür genügend Zeit ein.
Einige Empfehlungen wurden zur besseren Verständlichkeit überarbeitet und zusammengefasst.
Wie schon im Jahr 2021 haben sich auch in der „Season of Docs“ 2022 die meisten technischen Redakteure direkt bei den Organisationen beworben, mit denen sie zusammengearbeitet haben.
Häufige Probleme bei der Zusammenarbeit mit technischen Redakteuren
2022 wurden bei weniger Projekten Probleme bei der Zusammenarbeit mit technischen Redakteuren gemeldet. Das größte Problem war, dass technische Redakteure das Programm nicht abschließen konnten, weil sie krank waren, einen Vollzeitjob nahmen oder das Zeitlimit nicht erfüllen konnten.
In einem Projekt wurde berichtet, dass sein Dokumentationsprojekt von der Arbeit im Rahmen des Google Summer of Code abhängt und dass diese Abhängigkeiten schwer zu handhaben sind. Bei einem anderen Projekt traten Probleme auf, als die Hardware, die der technische Redakteur für die Dokumentation benötigte, vom Verteidigungsministerium im Land des Autors konfisziert und nicht importiert werden konnte.
Folgeumfragen
Den Teilnehmern des Jahres 2022 werden im Mai, August und November 2023 drei Folgeumfragen gesendet. Wir aktualisieren diesen Abschnitt mit den Ergebnissen, sobald sie vorliegen.
Zukünftige Fragen
Wie immer gilt: Je mehr wir über die Dokumentation in Open Source erfahren, desto mehr möchten wir lernen!
Für die Zukunft möchten wir Folgendes erreichen:
- Mehr Projektmetadaten erfassen, um nach Korrelationen zwischen Projektalter, Community-Größe oder Sprache und Dokumentationsbedarf zu suchen
- Dokumentationsprojekte analysieren, um festzustellen, ob sie in gemeinsam nutzbare Vorlagen verallgemeinert werden können
- Ein Bewertungsschema für Interviews mit technischen Redakteuren in Open-Source-Projekten entwickeln
Obwohl wir viele Fragen untersuchen möchten, möchten wir auch die Zeit der Open-Source-Projektadministratoren und -pfleger berücksichtigen, die an Season of Docs teilnehmen. Die oberste Priorität des Programms ist die Unterstützung von Projekten zur Lösung ihrer Probleme durch Dokumentation.