Aktuelle Phase:
Die „Season of Docs“-Saison 2021 wurde am 14. Dezember 2021 beendet. Siehe Zeitachse.
Über Staffel von Google Docs
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 2021
Programmänderungen 2021
In den Jahren 2019 und 2020 haben sich Organisationen und technische Redakteure jeweils separat für das Programm „Season of Docs“ beworben und technische Redakteure wurden von den Administratoren des Programms „Season of Docs“ mit Unternehmen abgeglichen. Die Organisationen stellten Mentoren für die Zusammenarbeit mit den technischen Redakteuren bereit, die je nach Standort ein Stipendium für ihre Arbeit erhielten. Im Rahmen des Programms wurde gemessen, ob die technischen Redakteure, Mentoren und Admins der Organisation mit ihrer Teilnahme am Programm zufrieden waren. Die Ergebnisse der Dokumentation wurden jedoch nicht gemessen.
Im Jahr 2021 nahm das „Season of Docs“-Team erhebliche Änderungen am Programm vor, wodurch der Fokus auf die Analyse der Dokumentationsergebnisse verlagerte und mehr Flexibilität für Organisationen und technische Redakteure ermöglichte.
- Organisationen, die sich mit Projektvorschlägen bewerben, einschließlich eines Budgets und vorgeschlagenen Metriken
- Technische Redakteure haben sich nicht mehr über Google für die Zusammenarbeit mit Organisationen beworben, sondern direkt bei den akzeptierten Organisationen beworben.
- Angenommene 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 abschließende Bewertungen und Fallstudien eingereicht und Folgeumfragen beantwortet.
Allgemeine Ergebnisse 2021
Organisationen
- Die Änderungen im Programm 2021 führten dazu, dass sich weniger Organisationen beworben haben (2021 haben sich 30% weniger beworben als 2020). Die Admins der Organisation waren jedoch 2021 etwas zufriedener mit dem Programm als die Administratoren im Jahr 2020 (93% gegenüber 91%).
Probleme, Dokumenttypen und Metriken
- Bei den meisten Projekten ging es um die Erstellung von Dokumentationen, um den Aufwand der Pflegekräfte zu reduzieren (durch die Reduzierung von Problemen/Fragen) und/oder die Projektbeteiligung (entweder durch Projektnutzer oder Mitwirkende) zu erhöhen.
- 50% der angenommenen Organisationen haben Anleitungs- oder Anleitungsinhalte erstellt.
- Mehr als 50% der angenommenen Organisationen hielten ihre aktuelle Dokumentation für mangelhaft, unorganisiert oder veraltet.
- Die Projekte wollten im Allgemeinen die Wirksamkeit der Dokumentation durch Interaktionen messen, insbesondere durch weniger Probleme und mehr Besucher der Dokumentation und die Beteiligung an Projekten.
- Bei 25 von 30 Projekten laut November 2022:
- 18 Projekte gaben an, ihre ursprünglichen Messwerte erreicht zu haben.
- 5 Projekte erfüllten überarbeitete Metriken
- 2 Projekte sagten, dass es noch zu früh sei, um das zu sagen
Programmteilnahme
- Die Anwerbung, Einstellung und Bezahlung technischer Redakteure war der schwierigste Teil des Programms für Organisationsadministratoren.
- Stand November 2022 haben 24 von 30 Organisationen geantwortet:
- 18 Organisationen arbeiteten noch mit den technischen Redakteuren von „Season of Docs“ zusammen (entweder als Mitarbeiter, die regelmäßig mitarbeiten oder als Ressource, um Fragen zu beantworten).
- 4 Unternehmen arbeiteten in einer bezahlten Rolle mit den technischen Redakteuren der „Season of Docs“-Reihe
- 18 Organisationen arbeiteten noch mit den technischen Redakteuren von „Season of Docs“ zusammen (entweder als Mitarbeiter, die regelmäßig mitarbeiten oder als Ressource, um Fragen zu beantworten).
Highlights 2021
- Mehrere Projekte gaben an, dass der technische Redakteur vorhatte, nach dem Ende des „Season of Docs“-Programms weiter an dem Projekt zu arbeiten.
- Metanorma hatte so viele qualifizierte technische Redakteure, dass sie passende Mittel fanden, um eine weitere Schriftstellerin einzustellen, die während des Programms mit der "Saison of Docs" unterstützt wird.
- Moja Global stellte fest, dass sich die Community sehr für die Dokumentation engagiert hat, und gründete eine neue Arbeitsgruppe für Dokumentationen, damit mehr Beitragende an der Projektdokumentation teilnehmen können.
Datenzusammenfassung für 2021
Im Jahr 2021 haben sich 82 Organisationen für das Programm beworben und 30 Open-Source-Organisationen wurden aufgenommen. Informationen zu den Auswahlkriterien finden Sie im Leitfaden zum Erstellen einer Anwendung. Die vollständige Liste der teilnehmenden Organisationen finden Sie auf der Website Season of Docs. Alle 30 akzeptierten Organisationen reichten ihren endgültigen Fallstudienbericht ein, um ihre Teilnahme am Programm 2021 abzuschließen.
Über die Organisationen
Die Organisationen, die an der „Season of Docs“ 2021 teilgenommen haben, vertreten eine Vielzahl von Open-Source-Projekten. Die Kohorte für 2021 umfasste Folgendes:
- Großsprachige Projekte wie Julia, Perl und R
- Projekte in den Bereichen Bildung, Klima, FinTech, Gesundheitswesen, Bibliotheksdienstleistungen, maschinelles Lernen, Massenspektrometrie, öffentliche Verträge und Robotik
- Entwicklerorientierte Projekte, einschließlich Chaos-Engineering-Tools, Fuzzers, Chatbot-SDKs, Pipelines zur Analyse der Softwarezusammensetzung, Tools zur Leistungsüberwachung und visuellen Programmiertools
- Dokumentationsprojekte für Dokumentationstools wie Redocly und Metanorma
Projekte des Python-Ökosystems waren die größte Unterkategorie. Die Kohorte von 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 Projekte gebeten, anzugeben, welche Open-Source-Lizenz sie verwendet haben.
Die von den Organisationen aus dem Jahr 2021 beschriebenen Dokumentationsprobleme sind sowohl in Open-Source-Projekten als auch in der technischen Dokumentation im Allgemeinen sehr häufige Probleme.
Zu den größten Problemen, die Unternehmen im Rahmen des Programms 2021 lösen wollten, waren:
Beachten Sie, dass Organisationen mehrere Dokumentationsprobleme melden können. Weitere Informationen finden Sie auf der Ergebnisseite „Season of Docs 2021“, auf der Sie Links zu vollständigen Fallstudien für jede Organisation finden.
Erstellte Dokumentationstypen
Tutorials waren in den Fallstudien aus dem Jahr 2021 der am häufigsten genannte Dokumentationstyp.
Weitere Dokumentationstypen, die in Fallstudien erwähnt werden, waren Docs-als-Code-Pipeline, Diagramm, Glossar, Styleguide, FAQs, Internationalisierung, Codelab, Inhaltsmodell, Module, Konzeptdokumentation, Fehlermeldungen, Nutzerstudien, Readme, Knowledgebase.
Einige dieser Kategorien sind ungenau und ein einzelnes Dokumentationsprojekt kann mehrere Dokumentationstypen oder Funktionen enthalten.
Bei mehreren Projekten wurde speziell das Diátaxis-Framework als Leitfaden für die Planung ihrer Dokumentationstypen verwendet.
Weitere Informationen finden Sie auf der Ergebnisseite „Season of Docs 2021“, auf der Sie Links zu vollständigen Fallstudien für jede Organisation finden.
Budgets
2021 betrugen die durchschnittlichen Budgetanforderungen 10.200 $und der Medianwert 10.000 $. Nur drei Organisationen haben die maximal mögliche Förderung (15.000 US-Dollar) beantragt und erhalten, und weitere drei haben den geringstmöglichen Zuschuss (5.000 US-Dollar) beantragt.
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 waren GitHub-Sterne, Verweildauer auf der Seite, Conversions in Mailinglisten, qualitative Nutzertests, Anzahl der Teilnehmer in Foren, Anzahl der Partner/Freiwilligen/Integrationen.
Aufgrund des kurzen Zeitraums zwischen dem Abschluss der Projekte zur technischen Erstellung und dem Einreichen der Fallstudien konnten die meisten Kohorten von 2021 nicht genügend Daten erheben, um festzustellen, ob die ursprünglichen Metriken erreicht wurden oder nicht.
Weitere Informationen finden Sie auf der Ergebnisseite „Season of Docs 2021“, auf der Sie Links zu vollständigen Fallstudien für jede Organisation finden.
Mit technischen Redakteuren zusammenarbeiten
Die größte Veränderung beim „Season of Docs“-Programm im Jahr 2021 war die Zusammenarbeit mit technischen Redakteuren. In früheren Saisons haben sich technische Redakteure direkt bei Google beworben und von den Programmadministratoren mit Projekten abgeglichen. Sie erhielten ein Pauschalstipendium direkt von Google.
2021 haben sich technische Redakteure direkt an den Projekten beworben und das Budget für die Vergütung der technischen Redakteure wurde über den Open Collective Fund der „Season of Docs“ gezahlt.
Die meisten der Projekte des 2021-Programms hatten wenig oder keine Erfahrung in der Anwerbung oder Einstellung technischer Redakteure. In vielen Projekten wurde dieser Teil des Prozesses als ein Prozess mit mehr Unterstützung benötigt. Als Reaktion auf dieses Feedback hat das „Season of Docs“-Team der Programmübersicht eine Dokumentation zum Erstellen von Vereinbarungen für technische Redakteure hinzugefügt.
Einstellungsempfehlungen
Die Projekte wurden gebeten, Empfehlungen für andere Projekte zu geben, die an einer Teilnahme an „Saison of Docs“ interessiert sind. Die besten Einstellungsempfehlungen waren:
- Teilen Sie die Anwerbungsmaterialien für technische Redakteure so früh wie möglich, noch bevor Sie in das Programm aufgenommen wurden. Bitte deine Community, potenzielle Kandidaten zu empfehlen.
- Teilen Sie Inhalte außerhalb der Projektkanäle. Verwenden Sie inklusive Sprache und ermuntern Sie Bewerber aus unterrepräsentierten Gruppen direkt, sich zu bewerben.
- Finden Sie heraus, welche Tools für den Prozess der Dokumentationserstellung wichtig sind, und rekrutieren Sie technische Redakteure, die Erfahrung im Umgang mit diesen Tools haben.
- Klare Erwartungen an den technischen Redakteur in Bezug auf Liefergegenstände und Meilensteine, Kommunikationskanäle und Kontaktaufnahmen sowie Zahlungsprozesse und -zeitplan formulieren.
- Investieren Sie in die Community und unterstützen Sie sie dabei, sich als technische Redakteure weiterzuentwickeln, indem Sie mit dem technischen Redakteur für „Season of Docs“ Mentoren und Coachings anbieten.
- Planen Sie mehr Zeit ein, als Sie für das Onboarding technischer Redakteure, die Beantwortung von Fragen und die Bereitstellung von Support während des Programms erwarten, insbesondere wenn die technische Redaktion noch keine Erfahrung im Bereich Ihres Projekts hat.
- Dokumentieren Sie Ihren Einstellungs- und Onboardingprozess für zukünftige Projekte.
(Hinweis: Nicht alle Projekte, die in ihren Fallstudien genannt werden und in denen sie Kandidaten für technische Redakteure rekrutiert haben.)
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 Familienverantwortung im Zusammenhang mit der Pandemie vom Programm ausgeschlossen werden. Bei einigen Projekten wurden Kommunikationsprobleme in Zusammenhang mit nicht übereinstimmenden Zeitzonen oder Problemen mit der Internetverbindung gemeldet.
Die Projekte stellten fest, dass sie die Schwierigkeiten beim Onboarding in ihren Communities oder bei der Einrichtung der Toolchain für ihr Projekt unterschätzt hatten.
Bei einigen Projekten gab es Verzögerungen bei der Bezahlung der technischen Redakteure, da es Probleme mit Banken bei Open Collective oder in den Heimatländern der Autoren gab. Es gab Zahlungsbeschränkungen.
Die Programmdokumentation zu Open Collective-Gebühren war nicht klar: Google nahm die Gebühren für die Open Collective-Transaktionsgebühren für den ersten Transfer von Geldern an die Projekte auf, aber keine Transaktionsgebühren, die von anderen Zahlungskanälen erhoben wurden (z. B. Währungsumrechnungsgebühren). Wir werden daran arbeiten, dies in der Dokumentation für zukünftige Programme klarer zu gestalten.
Folgeumfragen
Im Rahmen des „Season of Docs“-Programms wurden Projekte um die Teilnahme an Folgeumfragen gebeten. Im Mai, August und November 2022 wurden drei Umfragen gesendet.
In der Folgeumfrage wurden Projekte gebeten, zu bestätigen, dass ihre Links zu Angeboten und Fallstudien noch aktiv waren. Die Umfrage umfasste auch Fragen zum Erfolg ihrer Projekte (festgelegt anhand der Metriken, die sie in ihrer Fallstudie festgelegt haben) und zur fortlaufenden Beteiligung und Vergütung der technischen Autoren des Projekts:
- Arbeiten Sie noch mit dem technischen Redakteur für „Season of Docs“ zusammen?
- Wird die Fachkraft für technische Redakteure, die noch an Ihrem Projekt arbeitet, in irgendeiner Weise bezahlt?
- Ist Ihr Dokumentationsprojekt Ihrer Meinung nach nun erfolgreich?
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 erwarten wir Folgendes:
- Ob Projektdomains mit der Wahl des Dokumenttyps oder der Messwertauswahl korrelieren
- Welche Einstellungs- und Onboardingpraktiken für technische Redakteure am effektivsten für den Projektabschluss und die Bindung technischer Redakteure sind
- Vernünftige Zeitpläne für die Messung der Wirksamkeit der Dokumentation
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.