Season of Docs
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 2021
Programmänderungen 2021
2019 und 2020 haben sich Organisationen und technische Redakteure jeweils separat für das Season of Docs-Programm beworben. Die technischen Redakteure wurden dann von den Administratoren des Season of Docs-Programms mit Organisationen zusammengebracht. Organisationen stellten Mentoren zur Verfügung, die mit den technischen Redakteuren zusammenarbeiteten. Diese erhielten je nach Standort ein Stipendium für ihre Arbeit. Im Rahmen des Programms wurde gemessen, ob die technischen Redakteure, Mentoren und Administratoren der Organisation mit ihrer Teilnahme am Programm zufrieden waren. Die Ergebnisse der Dokumentation wurden jedoch nicht gemessen.
2021 hat das Season of Docs-Team das Programm erheblich geändert. Der Schwerpunkt wurde auf die Messung der Dokumentationsergebnisse gelegt und die Flexibilität für Organisationen und technische Redakteure erhöht.
- Organisationen, die mit Projektvorschlägen, einschließlich eines Budgets und vorgeschlagener Messwerte, ein Angebot eingereicht haben
- Technische Redakteure bewerben sich nicht mehr über Google, um mit Organisationen verglichen zu werden, sondern direkt bei den akzeptierten Organisationen.
- Die ausgewählten Organisationen erhielten über Open Collective Zuschüsse, mit denen sie technische Redakteure bezahlen konnten.
- Die Vergütung der technischen Redakteure wurde von den Organisationen festgelegt.
- Die Organisationen haben Abschlussbewertungen und Fallstudien eingereicht und Folgeumfragen beantwortet.
Allgemeine Ergebnisse 2021
Organisationen
- Die Änderungen am Programm 2021 haben zu weniger Bewerbungen geführt (30% weniger als 2020). Die Administratoren der teilnehmenden Organisationen waren jedoch etwas zufriedener mit dem Programm als die Administratoren von 2020 (93% gegenüber 91%).
Probleme, Dokumenttypen und Messwerte
- Bei den meisten Projekten lag der Schwerpunkt auf der Erstellung von Dokumentationen, um die Arbeitsbelastung der Maintainer zu reduzieren (durch weniger Probleme/Fragen) und/oder die Projektteilnahme zu erhöhen (entweder durch Projektnutzer oder Mitwirkende).
- 50% der ausgewählten Organisationen haben Anleitungen erstellt.
- Mehr als 50% der akzeptierten Organisationen empfanden ihre aktuelle Dokumentation als unzureichend, unorganisiert oder veraltet.
- Bei Projekten sollte die Effektivität der Dokumentation in der Regel anhand von Interaktionen gemessen werden, insbesondere an weniger gemeldeten Problemen, mehr Besuchern der Dokumente und mehr Beteiligung an Projekten.
- Stand November 2022 haben 25 von 30 Projekten geantwortet:
- 18 Projekte gaben an, ihre ursprünglichen Messwerte erreicht zu haben.
- 5 Projekte haben die überarbeiteten Messwerte erfüllt
- Bei zwei Projekten wurde angegeben, dass es noch zu früh ist, um eine Aussage zu treffen.
Programmteilnahme
- Die Rekrutierung, Einstellung und Bezahlung von technischen Redakteuren war der schwierigste Teil des Programms für die Administratoren der Organisation.
- Stand November 2022 haben 24 von 30 Organisationen geantwortet:
- 18 Organisationen arbeiteten noch mit ihren technischen Redakteuren von Season of Docs zusammen (entweder als kontinuierlicher Mitwirkender oder als Ressource zur Beantwortung von Fragen).
- 4 Organisationen haben ihre technischen Redakteure von Season of Docs in einer bezahlten Position beschäftigt
- 18 Organisationen arbeiteten noch mit ihren technischen Redakteuren von Season of Docs zusammen (entweder als kontinuierlicher Mitwirkender oder als Ressource zur Beantwortung von Fragen).
Highlights 2021
- Bei mehreren Projekten wurde angegeben, dass die technischen Redakteure auch nach dem Ende des Season of Docs-Programms an ihrem Projekt weiterarbeiten möchten.
- Metanorma erhielt so viele Bewerbungen von qualifizierten technischen Redakteuren, dass es die Mittel fand, um einen zusätzlichen Redakteur einzustellen, der während des Programms mit dem von Season of Docs unterstützten Redakteur zusammenarbeiten sollte.
- Moja Global stellte fest, dass die Community sehr engagiert an der Dokumentation war, und richtete eine neue Arbeitsgruppe für die Dokumentation ein, damit mehr Mitwirkende an der Projektdokumentation teilnehmen konnten.
Zusammenfassungsdaten für 2021
2021 haben sich 82 Organisationen beworben und 30 Open-Source-Organisationen wurden in das Programm aufgenommen. Die Auswahlkriterien finden Sie im Leitfaden zum Erstellen einer Bewerbung. Eine vollständige Liste der teilnehmenden Organisationen finden Sie auf der Website von Season of Docs. Alle 30 zugelassenen Organisationen haben ihren endgültigen Fallstudienbericht eingereicht, um ihre Teilnahme am Programm 2021 abzuschließen.
Informationen zu den Organisationen
Die an der Season of Docs 2021 teilnehmenden Organisationen repräsentierten eine Vielzahl von Open-Source-Projekten. Die Kohorte 2021 umfasste:
- Große Sprachprojekte wie Julia, Perl und R
- Projekte in den Bereichen Bildung, Klima, FinTech, Gesundheitswesen, Bibliotheksdienste, maschinelles Lernen, Massenspektrometrie, öffentliche Aufträge und Robotik
- Entwicklerorientierte Projekte, einschließlich Chaos-Engineering-Tools, Fuzzern, Chatbot-SDKs, Pipelines zur Analyse der Softwarezusammensetzung, Tools zur Leistungsüberwachung und visuellen Programmiertools
- Dokumentationsprojekte für Dokumentationstools wie Redocly und Metanorma
Projekte zur Python-Umgebung waren die größte Unterkategorie. Die Kohorte 2021 umfasste ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite und SymPy.
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 von den Organisationen 2021 beschriebenen Dokumentationsprobleme sind sowohl in Open-Source-Projekten als auch in technischer Dokumentation im Allgemeinen sehr häufig.
Zu den wichtigsten Problemen, die die Unternehmen im Programm 2021 lösen wollten, gehörten:
Hinweis: Organisationen können mehrere Dokumentationsprobleme melden. Weitere Informationen finden Sie auf der Ergebnisseite der Season of Docs 2021, auf der es Links zu vollständigen Fallstudien für jede Organisation gibt.
Erstellte Dokumentationstypen
In den Fallstudien von 2021 wurden Tutorials am häufigsten als Dokumentationstyp genannt.
Weitere in den Fallstudien erwähnte Dokumentationstypen waren Docs-as-Code-Pipeline, Diagramm, Glossar, Styleguide, FAQs, Internationalisierung, Codelab, Inhaltsmodell, Module, Konzeptdokumentation, Fehlermeldungen, Nutzerstudien, Readme, Wissensdatenbank.
Einige dieser Kategorien sind unscharf und ein einzelnes Dokumentationsprojekt kann mehrere Dokumentationstypen oder -funktionen enthalten.
Bei mehreren Projekten wurde das Diátaxis-Framework als Leitfaden für die Planung der Dokumentationstypen verwendet.
Weitere Informationen finden Sie auf der Ergebnisseite der Season of Docs 2021, auf der es Links zu vollständigen Fallstudien für jede Organisation gibt.
Budgets
2021 betrug der durchschnittliche Budgetantrag 10.200 $und der Median 10.000 $. Nur drei Organisationen haben den maximal möglichen Zuschuss in Höhe von 15.000 $ beantragt und erhalten, weitere drei haben den niedrigsten Zuschuss in Höhe von 5.000 $ beantragt.
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 waren GitHub-Sterne, Zeit auf der Seite, Conversions über die Mailingliste, qualitative Nutzertests, Anzahl der Teilnehmer in Foren, Anzahl der Partner/Freiwilligen/Integrationen.
Aufgrund des kurzen Zeitraums zwischen dem Abschluss der technischen Schreibprojekte und dem Einreichen der Fallstudien konnte der Großteil der Kohorte 2021 nicht genügend Daten erheben, um festzustellen, ob die ursprünglichen Messwerte erreicht wurden.
Weitere Informationen finden Sie auf der Ergebnisseite der Season of Docs 2021, auf der es Links zu vollständigen Fallstudien für jede Organisation gibt.
Zusammenarbeit mit technischen Redakteuren
Die größte Änderung am Season of Docs-Programm 2021 betraf die Zusammenarbeit von Projekten mit technischen Redakteuren. In früheren Staffeln haben sich Technische Redakteure direkt bei Google beworben und wurden von den Programmadministratoren Projekten zugewiesen. Sie erhielten ein festes Stipendium direkt von Google.
2021 bewarben sich Technische Redakteure direkt bei den Projekten und die Projekte legten das Budget für die Vergütung der Technischen Redakteure fest. Die Zahlungen erfolgten über den Open Collective-Fonds von Season of Docs.
Die meisten Projekte, die am Programm 2021 teilgenommen haben, hatten wenig oder keine Erfahrung mit der Rekrutierung oder Einstellung von technischen Redakteuren. Viele Projekte gaben an, dass dieser Teil des Prozesses mehr Unterstützung benötigt. Als Reaktion auf dieses Feedback hat das Season of Docs-Team dem Programmleitfaden Dokumentation zum Erstellen von Vereinbarungen für technische Redakteure hinzugefügt.
Empfehlungen für die Personalbeschaffung
Die Projekte wurden gebeten, Empfehlungen für andere Projekte abzugeben, die an der Season of Docs teilnehmen möchten. Die wichtigsten Empfehlungen für die Personalbeschaffung waren:
- Teilen Sie die Rekrutierungsmaterialien für technische Redakteure so früh wie möglich mit, auch bevor Sie in das Programm aufgenommen wurden. Bitte deine Community, mögliche Kandidaten zu empfehlen.
- Die Inhalte werden außerhalb der Projektkanäle weithin geteilt. Verwenden Sie inklusive Sprache und ermutigen Sie Kandidaten mit einem unterrepräsentierten Hintergrund direkt, sich zu bewerben.
- Informieren Sie sich, welche Tools für die Erstellung Ihrer Dokumentation unerlässlich sind, und stellen Sie technische Redakteure ein, die Erfahrung mit diesen Tools haben.
- Legen Sie klare Erwartungen an den technischen Redakteur in Bezug auf die zu liefernden Dokumente und Meilensteine, Kommunikationskanäle und -abläufe sowie Zahlungsprozesse und Zeitplan fest.
- Sie können in Communitymitglieder investieren und ihnen helfen, sich als technische Redakteure weiterzuentwickeln, indem Sie das Programm „Season of Docs“ für technische Redakteure nutzen, um Mentoring und Coaching anzubieten.
- Planen Sie mehr Zeit als erwartet für das Onboarding von technischen Redakteuren, das Beantworten von Fragen und die Unterstützung während des Programms ein, insbesondere wenn der technische Redakteur keine vorherige Erfahrung in der Branche Ihres Projekts hat.
- Dokumentieren Sie Ihren Rekrutierungsprozess, die Einstellung und das Onboarding, um sie für zukünftige Projekte zu verwenden.
Hinweis: Nicht alle Projekte in den Fallstudien geben an, wo die Kandidaten für technisches Schreiben rekrutiert wurden.
Häufige Probleme bei der Zusammenarbeit mit technischen Redakteuren
Technische Redakteure in mehreren Projekten mussten aufgrund von COVID-19 oder anderen Krankheiten oder aufgrund von familiären Verpflichtungen im Zusammenhang mit der Pandemie aussteigen. Bei einigen Projekten wurden Kommunikationsprobleme aufgrund von Zeitzonenverschiebungen oder Internetverbindungsproblemen gemeldet.
Die Teams stellten fest, dass sie die Schwierigkeiten beim Onboarding in ihren Communities oder beim Einrichten der Docs-Toolchain ihres Projekts unterschätzt hatten.
Bei einigen Projekten kam es aufgrund von Bankproblemen mit Open Collective oder aufgrund von Zahlungseinschränkungen in den Heimatländern der Autoren zu Verzögerungen bei der Zahlung an die technischen Redakteure.
Die Programmdokumentation zu Open Collective-Gebühren war nicht klar: Google übernahm die Open Collective-Transaktionsgebühren für die erste Überweisung von Geldern an die Projekte, aber nicht die Transaktionsgebühren, die von anderen Zahlungskanälen erhoben wurden (z. B. Gebühren für die Währungsumrechnung). Wir werden versuchen, dies in der Dokumentation für zukünftige Programme klarer zu formulieren.
Folgeumfragen
Im Rahmen des Season of Docs-Programms wurden die Projekte gebeten, an Folgeumfragen teilzunehmen. Im Mai, August und November 2022 wurden drei Umfragen gesendet.
In der Folgeumfrage wurden die Projekte gebeten, zu bestätigen, dass die Links zu ihren Vorschlägen und Fallstudien noch aktiv waren. Die Umfrage enthielt auch Fragen zum Erfolg ihrer Projekte (gemessen anhand der in der Fallstudie festgelegten Messwerte) und zur weiteren Teilnahme und Vergütung der technischen Redakteure des Projekts:
- Arbeiten Sie noch mit Ihrem technischen Redakteur von Season of Docs zusammen?
- Wird der Technische Redakteur, der noch an Ihrem Projekt arbeitet, in irgendeiner Weise entlohnt?
- Sind Sie der Meinung, dass Ihr Dokumentationsprojekt zu diesem Zeitpunkt erfolgreich ist?
Zukünftige Fragen
Wie immer gilt: Je mehr wir über Open-Source-Dokumentation erfahren, desto mehr möchten wir lernen. In zukünftigen Saisons hoffen wir, Folgendes zu erfahren:
- Ob Projektdomains mit der Auswahl des Dokumenttyps oder des Messwerts korreliert sind
- Welche Praktiken bei der Einstellung und Einarbeitung von technischen Redakteuren sind am effektivsten für die Projektabwicklung und die Bindung von technischen Redakteuren?
- Angemessene Zeitpläne für die Messung der Effektivität der Dokumentation
Es gibt viele Fragen, die wir gerne beantworten 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.