Aktuelle Phase:
Die Saison 2021 für Google Docs wurde am 14. Dezember 2021 beendet. Siehe Zeitachse.
Über die Staffel von Google Docs
Season of Docs ist ein Nachhaltigkeitsprogramm, das vom Google Open Source Programs Office verwaltet wird. Mit „Season of Docs“ haben Sie folgende Ziele:
- 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 aufmerksam machen
- Informationen zu effektiven Messwerten in der Open-Source-Dokumentation erheben und teilen
Weitere Informationen zur Season of 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. Die technischen Redakteure wurden von den „Season of Docs“-Programmadministratoren mit Organisationen abgeglichen. Die Organisationen stellten Mentoren für die Arbeit mit den technischen Redakteuren zur Verfügung, die je nach Standort ein Gehalt für ihre Arbeit erhielten. Im Rahmen des Programms wurde gemessen, ob die technischen Autoren, Mentoren und Administratoren 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. Dadurch verlagerte sich der Fokus auf die Messung der Dokumentationsergebnisse und sorgte für mehr Flexibilität für Organisationen und technische Redakteure.
- Organisationen, die sich mit Projektvorschlägen beworben haben, einschließlich eines Budgets und vorgeschlagener Messwerte
- Technische Autoren haben sich nicht mehr über Google für den Abgleich mit Organisationen beworben, sondern sich direkt bei den akzeptierten Organisationen beworben.
- Akzeptierte Organisationen erhielten über Open Collective Zuschüsse, mit denen sie früher 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 von 2021 führten dazu, dass sich weniger Organisationen beworben haben (2021 haben wir im Vergleich zu 2020 30% weniger Bewerbungen gesehen), aber die Administratoren der Organisationen 2021 waren etwas zufriedener mit dem Programm als die Administratoren von 2020 (93% gegenüber 91%).
Probleme, Dokumenttypen und Messwerte
- Die meisten Projekte konzentrierten sich auf die Erstellung von Dokumentationen, um den Aufwand der Pflegekräfte zu reduzieren (durch die Reduzierung von Problemen/Fragen) und/oder die Projektbeteiligung zu erhöhen (entweder durch Projektnutzer oder Mitwirkende).
- 50% der akzeptierten Organisationen haben Anleitungs- oder Anleitungsinhalte erstellt.
- Mehr als 50% der akzeptierten Organisationen hielten ihre aktuelle Dokumentation für mangelhaft, unorganisiert oder veraltet.
- Die Projekte wollten die Wirksamkeit der Dokumentation durch Interaktionen messen, insbesondere durch weniger Probleme und mehr Besucher der Dokumente und die Beteiligung an Projekten.
- Bei 25 von 30 Projekten (Stand November 2022) reagierten 25 von 30 Projekten auf Folgendes:
- 18 Projekte gaben an, ihre ursprünglichen Metriken zu erfüllen
- 5 Projekte hatten überarbeitete Metriken
- 2 Projekten sagten, es sei noch zu früh, um das zu sagen
Programmteilnahme
- Das Anwerben, Einstellen und Bezahlen von technischen Redakteuren war der schwierigste Teil des Programms für Organisationsadministratoren.
- 24 von 30 Organisationen haben im November 2022 geantwortet:
- 18 Organisationen arbeiteten noch mit den technischen Redakteuren der „Season of Docs“ zusammen – entweder als Beitragende oder als Ressource, um Fragen zu beantworten.
- 4 Organisationen arbeiteten in einer bezahlten Rolle mit den technischen Redakteuren der „Season of Docs“ zusammen
- 18 Organisationen arbeiteten noch mit den technischen Redakteuren der „Season of Docs“ zusammen – entweder als Beitragende oder als Ressource, um Fragen zu beantworten.
Highlights 2021
- Mehrere Projekte gaben an, dass der technische Redakteur vorhatte, nach dem Ende des Programms „Season of Docs“ weiter an dem Projekt zu arbeiten.
- Metanorma ließ sich von so vielen qualifizierten technischen Redakteuren bewerben, dass sie passende Mittel fanden, um einen weiteren Autor einzustellen, der während des Programms an der „Season of Docs – unterstützter Schriftstellerin“ arbeitete.
- Moja Global stellte fest, dass sich die Gemeinschaft sehr in Bezug auf Dokumentation engagiert, und gründete eine neue Arbeitsgruppe für Dokumentationen, damit mehr Beitragende sich an der Projektdokumentation beteiligen können.
Datenzusammenfassung für 2021
2021 haben sich 82 Organisationen beworben und 30 Open-Source-Organisationen wurden für das Programm zugelassen. 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 abschließenden Fallstudienbericht ein, um ihre Teilnahme am Programm für 2021 abzuschließen.
Über die Organisationen
Die Organisationen, die an der Season of Docs 2021 teilgenommen haben, repräsentierten eine Vielzahl von Open-Source-Projekten. Die Kohorte für 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, Fuzzers, Chatbot-SDKs, Pipelines für die Analyse der Softwarezusammensetzung, Tools zur Leistungsüberwachung und visuellen Programmiertools
- Dokumentationsprojekte für Dokumentationstools wie Redocly und Metanorma
Python-Projekte 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 (wie das Gründungsdatum, die geografische Verteilung der Mitwirkenden, die Anzahl der Mitwirkenden oder die 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 bei Open-Source-Projekten als auch in der technischen Dokumentation im Allgemeinen sehr häufige Probleme.
Zu den wichtigsten Problemen, die sich Unternehmen mit dem Programm 2021 hofften, gehörten:
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.
Mehrere Projekte, auf die speziell das Diátaxis-Framework als Leitfaden für die Planung ihrer Dokumentationstypen verwendet wird
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 betrug die durchschnittliche Budgetanforderung 10.200 $und der Medianwert 10.000 $. Nur drei Organisationen haben die maximal mögliche Förderung (15.000 US-Dollar) beantragt und erhalten. Weitere drei haben die geringstmögliche Förderung (5.000 US-Dollar) angefordert.
Messwerte
Die Projekte beschreiben in ihren Fallstudien die Metriken, mit denen sie den Erfolg ihrer Dokumentationsprojekte bewerteten.
Die wichtigsten vorgeschlagenen Messwerte waren:
Weitere vorgeschlagene Messwerte waren GitHub-Sterne, Zeit 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 des technischen Schreibens und dem Einreichen der Fallstudien konnten die meisten der Kohorten von 2021 nicht genügend Daten sammeln, um festzustellen, ob ihre anfänglichen Messwerte erfüllt 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 Änderung am Programm „Season of Docs“ im Jahr 2021 war, wie Projekte mit technischen Redakteuren zusammengearbeitet wurden. In früheren Saisons haben sich technische Redakteure direkt bei Google beworben. Die Programmadministratoren erhielten Projekte und erhielten ein Pauschalstipendium direkt von Google.
Im Jahr 2021 bewarben sich technische Redakteure direkt bei den Projekten und die Projekte legten das Budget für die Vergütung technischer Redakteure fest. Die Zahlungen erfolgten über den Open Collective Fund der „Season of Docs“.
Die meisten der Projekte, die am Programm 2021 teilnehmen, hatten wenig oder keine Erfahrung in der Rekrutierung oder Einstellung von technischen Redakteuren. In vielen Projekten wurde dieser Teil des Prozesses als ein Teil des Prozesses bezeichnet, der mehr Unterstützung erfordert. 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 sollten Empfehlungen für andere Projekte geben, die an einer Teilnahme an „Season 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. Bitten Sie Ihre Community, potenzielle Kandidaten zu empfehlen.
- Teilen Sie Inhalte außerhalb der Projektkanäle. Verwenden Sie inklusive Sprache und ermutigen Sie Kandidaten aus unterrepräsentierten Gruppen direkt, sich zu bewerben.
- Finden Sie heraus, welche Tools für den Prozess der Dokumentationserstellung unerlässlich 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 -zeitpunkt definieren
- Investieren Sie in Ihre Community-Mitglieder und unterstützen Sie sie dabei, sich als technische Redakteure weiterzuentwickeln. Nutzen Sie die Zeit, um als technische Redakteurin für das Saisongeschäft von Google Docs zusammenzuarbeiten, um Mentoren und Coachings zur Verfügung zu stellen.
- 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 der technische Redakteur keine Erfahrung mit der Domain Ihres Projekts hat.
- Dokumentieren Sie Ihren Einstellungs- und Onboardingprozess für zukünftige Projekte.
(Hinweis: Nicht alle Projekte, die in ihren Fallstudien aufgeführt sind und für die sie Kandidaten für technische Redakteure rekrutieren.)
Häufige Probleme bei der Zusammenarbeit mit technischen Redakteuren
Technische Autoren mussten in mehreren Projekten aufgrund von COVID-19 oder anderen Erkrankungen oder aufgrund von Familienverantwortlichkeiten im Zusammenhang mit der Pandemie das Programm beenden. Bei einigen Projekten wurden Kommunikationsprobleme aufgrund nicht übereinstimmender Zeitzonen oder Probleme 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ätzten.
Bei einigen Projekten gab es Verzögerungen bei der Bezahlung der technischen Redakteure aufgrund von Bankproblemen bei Open Collective oder weil es in den Heimatländern der Autoren Zahlungsbeschränkungen gab.
Die Programmdokumentation zu Open Collective-Gebühren war nicht klar: Google deckte die Open Collective-Transaktionsgebühren für den ursprünglichen Transfer von Geldern an die Projekte ab, nicht jedoch die Transaktionsgebühren, die von einigen anderen Zahlungskanälen erhoben wurden (z. B. Währungsumrechnungsgebühren). Wir werden dies in der Dokumentation für zukünftige Programme verdeutlichen.
Folgeumfragen
Im Rahmen des Programms „Season of Docs“ wurden die Projekte zur Teilnahme an Folgeumfragen aufgefordert. Im Mai, August und November 2022 wurden drei Umfragen gesendet.
In der Folgeumfrage wurden Projekte gebeten, zu bestätigen, dass die Links für den Vorschlag und die Fallstudie 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 projekttechnischen Redakteure:
- Arbeiten Sie noch mit der technischen Redaktion der „Season of Docs“ zusammen?
- Wird Ihr technischer Redakteur in irgendeiner Weise bezahlt, falls er noch an Ihrem Projekt arbeitet?
- Haben Sie jetzt das Gefühl, dass Ihr Dokumentationsprojekt erfolgreich ist?
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 kommenden Saisons erwarten wir von Ihnen folgende Informationen:
- Ob Projektdomains mit der DOCTYPE-Auswahl oder Messwertauswahl korrelieren
- Welche Praktiken zum Einstellen und Onboarding von technischen Redakteuren für den Projektabschluss und die Bindung technischer Redakteure am effektivsten sind
- Vernünftige Zeitpläne für die Messung der Wirksamkeit der Dokumentation
Obwohl wir vielen Fragen gerne nachgehen 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 von Problemen durch die Dokumentation.