Phase actuelle:
Le programme Season of Docs 2021 s'est terminé le 14 décembre 2021. Consultez la chronologie.
À propos de Season of Docs
Season of Docs est un programme de développement durable géré par le Bureau des programmes Open Source de Google. Les objectifs de Season of Docs sont les suivants:
- Fournir une assistance pour les projets Open Source afin de résoudre les problèmes des projets à l'aide de la documentation
- Donner aux rédacteurs techniques la possibilité d'acquérir de l'expérience dans l'Open Source
- Sensibiliser à l'Open Source, à la documentation et à la rédaction technique
- Collectez et partagez des informations sur les métriques efficaces dans la documentation Open Source.
Vous trouverez plus d'informations sur Season of Docs sur le site Web du programme.
Présentation du programme 2021
Modifications du programme en 2021
En 2019 et 2020, les organisations et les rédacteurs techniques ont chacun postulé séparément au programme Season of Docs, et les rédacteurs techniques ont été mis en relation avec des organisations par les administrateurs du programme Season of Docs. Les organisations ont proposé des mentors pour travailler avec les rédacteurs techniques, qui ont reçu une rémunération en échange de leur lieu de travail. Le programme a mesuré si les rédacteurs techniques, les mentors et les administrateurs de l'organisation étaient satisfaits de leur participation, mais n'a pas mesuré les résultats de la documentation.
En 2021, l'équipe Season of Docs a apporté d'importantes modifications au programme, en se concentrant sur la mesure des résultats de la documentation et en offrant plus de flexibilité aux organisations et aux rédacteurs techniques.
- Organisations associées à des propositions de projets, y compris un budget et des métriques proposées
- Les rédacteurs techniques n'ont plus postulé via Google pour être mis en correspondance avec des organisations, mais ont postulé directement aux organisations acceptées
- Les organisations acceptées ont reçu des subventions via Open Collective, qu'elles utilisaient pour payer les rédacteurs techniques.
- La rémunération des rédacteurs techniques était définie par les organisations
- Les organisations ont envoyé des évaluations finales et des études de cas, ainsi que des enquêtes de suivi.
Résultats généraux de 2021
Organisations
- Les changements intervenus dans le programme 2021 ont réduit le nombre d'organisations qui ont postulé (30% d'organisations en moins en 2021 par rapport à 2020). Toutefois, en 2021, les administrateurs de l'organisation ont été légèrement plus satisfaits du programme que les administrateurs de 2020 (93% contre 91%).
Problèmes, types de documents et métriques
- La plupart des projets se sont concentrés sur la création de documents pour réduire la charge du responsable (en réduisant les problèmes/questions) et/ou augmenter la participation au projet (que ce soit par les utilisateurs du projet ou les contributeurs).
- 50% des organisations acceptées ont créé des tutoriels ou des vidéos pratiques.
- Plus de 50% des organisations acceptées considèrent que leurs documents actuels manquent, désorganisés ou obsolètes.
- Les projets visaient généralement à mesurer l'efficacité de leur documentation par le biais d'interactions, en particulier la réduction du nombre de problèmes soulevés, l'augmentation du nombre de visiteurs des documents et la participation aux projets.
- En novembre 2022, 25 projets sur les 30 ont répondu :
- 18 projets ont déclaré avoir atteint leurs métriques d'origine
- 5 projets avaient respecté les métriques révisées
- 2 projets ont indiqué qu'il était encore trop tôt pour le dire
Participation au programme
- Le recrutement, l'embauche et la rémunération de rédacteurs techniques ont été la partie la plus difficile du programme pour les administrateurs d'une organisation.
- En novembre 2022, 24 organisations sur 30 ont répondu :
- 18 organisations travaillaient encore avec leurs rédacteurs techniques pour Season of Docs (en tant que contributeur continu ou en tant que ressource pour répondre aux questions).
- 4 organisations occupaient un poste rémunéré avec leur rédacteur technique Season of Docs.
- 18 organisations travaillaient encore avec leurs rédacteurs techniques pour Season of Docs (en tant que contributeur continu ou en tant que ressource pour répondre aux questions).
Temps forts de 2021
- Plusieurs projets ont indiqué que leur rédacteur technique avait l'intention de continuer à travailler sur leur projet après la fin du programme Season of Docs
- Metanorma disposait de tellement de rédacteurs techniques qualifiés qui ont postulé qu'ils ont trouvé des fonds correspondants afin d'embaucher un rédacteur supplémentaire pour travailler aux côtés de l'auteur soutenant la saison de Docs pendant le programme.
- Moja Global a constaté que la communauté était très impliquée dans la documentation et a mis en place un nouveau groupe de travail sur la documentation pour permettre à davantage de contributeurs de participer à la documentation du projet
Données récapitulatives de 2021
En 2021, 82 organisations ont postulé et 30 organisations Open Source ont été acceptées dans le programme. Pour connaître les critères de sélection, consultez le guide Créer une application. La liste complète des organisations participantes est disponible sur le site Web Season of Docs. Les 30 organisations acceptées ont envoyé leur rapport d'étude de cas final pour finaliser leur participation au programme 2021.
À propos des organisations
Les organisations participant à Season of Docs 2021 représentaient un large éventail de projets Open Source. La cohorte 2021 comprenait:
- Grands projets de langage tels que Julia, Perl et R
- Projets dans les domaines de l'éducation, du climat, de la fintech, de la santé, des services de bibliothèque, du machine learning, de la spectrométrie de masse, des contrats publics et de la robotique
- Projets destinés aux développeurs, y compris des outils d'ingénierie du chaos, des fuzzers, des SDK chatbots, des pipelines d'analyse de composition logicielle, des outils de surveillance des performances et des outils de programmation visuelle
- Projets de documentation pour des outils tels que Redocly et Metanorma
Les projets de l'écosystème Python constituaient la sous-catégorie la plus importante. La cohorte 2021 comprenait ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite et SymPy.
Nous n'avons pas collecté de métadonnées sur les projets (telles que la date de création, la répartition géographique des contributeurs, le nombre de contributeurs ou la taille de la base d'utilisateurs).
Nous avons demandé aux projets d'indiquer la licence Open Source qu'ils utilisaient.
Les problèmes de documentation décrits par les organisations en 2021 sont très courants dans les projets Open Source et dans la documentation technique en général.
Voici les principaux problèmes que les organisations espéraient résoudre lors du programme 2021:
Notez que les organisations peuvent signaler plusieurs problèmes de documentation. Pour en savoir plus, consultez la page des résultats de Season of Docs 2021, qui renvoie vers des études de cas complètes pour chaque organisation.
Types de documents créés
Les tutoriels sont le type de documentation le plus souvent mentionné dans les études de cas de 2021.
Les autres types de documentation mentionnés dans les études de cas sont les suivants : pipeline Docs en tant que code, schéma, glossaire, guide de style, questions fréquentes, internationalisation, atelier de programmation, modèle de contenu, modules, documentation sur les concepts, messages d'erreur, recherche utilisateur, Readme et Knowledgebase.
Certaines de ces catégories sont confus et un seul projet de documentation peut contenir plusieurs types de documentation ou fonctionnalités.
Plusieurs projets spécifiquement référencés en utilisant le framework Diataxis pour la planification de leurs types de documentation.
Pour en savoir plus, consultez la page des résultats de Season of Docs 2021, qui renvoie vers des études de cas complètes pour chaque organisation.
Budgets
En 2021, la demande de budget moyenne s'élevait à 10 200 $et la médiane à 10 000 $. Seules trois organisations ont demandé et reçu la subvention maximale (15 000 $), et trois autres ont demandé la subvention la plus faible possible (5 000 $).
Métriques
Les projets décrivent dans leurs études de cas les mesures qu'ils utilisaient pour évaluer le succès de leurs projets de documentation.
Voici les principales métriques proposées:
Les autres métriques proposées comprenaient les étoiles GitHub, le temps passé sur la page, les conversions sur les listes de diffusion, les tests utilisateur qualitatifs, le nombre de participants aux forums et le nombre de partenaires/bénévoles/intégrations.
En raison du court laps de temps entre la fin des projets de rédaction technique et l'envoi des études de cas, la plupart des membres de la cohorte 2021 n'avaient pas pu collecter suffisamment de données pour déterminer si leurs métriques initiales avaient été atteintes ou non.
Pour en savoir plus, consultez la page des résultats de Season of Docs 2021, qui renvoie vers des études de cas complètes pour chaque organisation.
Travailler avec des rédacteurs techniques
Le plus grand changement apporté au programme Season of Docs en 2021 concerne la collaboration des projets avec les rédacteurs techniques. Au cours des saisons précédentes, les rédacteurs techniques postulaient directement à Google, étaient mis en relation avec les administrateurs du programme avec des projets et recevaient une rémunération forfaitaire directement de Google.
En 2021, les rédacteurs techniques ont postulé directement aux projets, et les projets définissent le budget de leur rémunération, les paiements étant effectués via le fonds Open Collective Season of Docs.
La plupart des projets participant au programme de 2021 avaient peu ou pas d’expérience dans le recrutement de rédacteurs techniques, et de nombreux projets ont décrit cette partie du processus comme une partie nécessitant plus de soutien. En réponse à ces commentaires, l'équipe Season of Docs a ajouté au guide des programmes de la documentation sur la création d'accords pour les rédacteurs techniques.
Recommandations d'embauche
Les projets ont été invités à faire des recommandations pour d’autres projets intéressés par participer à Season of Docs. Voici les principales recommandations d'embauche:
- Partagez les documents de recrutement pour les rédacteurs techniques dès que possible, avant même d'avoir été accepté dans le programme. Demandez aux membres de votre communauté de parrainer d'éventuels candidats.
- Partager largement en dehors des canaux du projet. Utilisez un langage inclusif et encouragez directement les candidats issus de milieux sous-représentés à postuler.
- Comprendre quels outils sont essentiels à votre processus de création de documentation et recruter des rédacteurs techniques ayant de l’expérience dans l’utilisation de ces outils.
- Définir des attentes claires pour le rédacteur technique en ce qui concerne les produits livrables et les jalons, les canaux de communication et les contrôles, ainsi que les processus et les délais de paiement.
- Vous pouvez envisager d'investir dans les membres de la communauté et de les aider à progresser en tant que rédacteurs techniques en faisant appel à la rédactrice technique pour la saison de Docs pour vous accompagner et vous encadrer.
- Prévoyez plus de temps que prévu pour intégrer les rédacteurs techniques, répondre aux questions et fournir un soutien au cours du programme, surtout si le rédacteur technique n’a pas d’expérience préalable dans le domaine de votre projet.
- Documentez votre processus de recrutement, d'embauche et d'intégration afin de l'utiliser pour de futurs projets.
(Remarque: tous les projets ne sont pas indiqués dans leurs études de cas pour lesquelles ils ont recruté leurs candidats rédacteurs techniques.)
Problèmes courants de collaboration avec les rédacteurs techniques
Les rédacteurs techniques de plusieurs projets ont dû abandonner le travail en raison de la COVID ou d'autres maladies, ou en raison de responsabilités familiales liées à la pandémie. Certains projets ont signalé des problèmes de communication impliquant des incohérences de fuseau horaire ou des problèmes de connectivité Internet.
Les projets ont découvert qu'ils sous-estimaient les difficultés liées à l'intégration dans leurs communautés ou à la configuration de la chaîne d'outils de documents de leurs projets.
Certains projets ont eu des retards dans le paiement de leurs rédacteurs techniques en raison de problèmes bancaires avec Open Collective ou parce que les pays d’origine des auteurs avaient des restrictions de paiement.
La documentation du programme concernant les frais Open Collective n'était pas claire: Google a pris en charge les frais de transaction Open Collective pour le transfert initial des fonds vers les projets, mais pas les frais de transaction imposés par d'autres canaux de paiement (tels que les frais de conversion de devises). Nous nous efforcerons de clarifier cela dans la documentation des futurs programmes.
Enquêtes de suivi
Dans le cadre du programme Season of Docs, les projets ont été invités à participer à des enquêtes de suivi. Trois enquêtes ont été envoyées en mai, août et novembre 2022.
L'enquête de suivi a demandé aux projets de confirmer que les liens vers leur proposition et leur étude de cas étaient toujours actifs. L’enquête comprenait également des questions sur la réussite de leurs projets (tel que déterminé par les mesures qu’ils ont définies dans leur étude de cas) et la participation continue et la rémunération des rédacteurs techniques du projet:
- Travaillez-vous toujours avec votre rédacteur technique pour Season of Docs ?
- Si votre rédacteur technique travaille toujours sur votre projet, est-il rémunéré d'une quelconque façon ?
- À ce stade, pensez-vous que votre projet de documentation porte ses fruits ?
Questions futures
Comme toujours, plus nous en apprenons sur la documentation en open source, plus nous voulons en apprendre ! Au cours des prochaines saisons, nous espérons apprendre:
- Indique si les domaines du projet sont corrélés au choix du type de document ou du choix des métriques
- Quelles sont les pratiques d'embauche et d'intégration des rédacteurs techniques les plus efficaces pour l'achèvement du projet et la rétention des rédacteurs techniques
- Délais raisonnables pour mesurer l'efficacité de la documentation
Bien qu'il y ait beaucoup de questions sur lesquelles nous aimerions répondre, nous tenons également à respecter le temps des administrateurs et des responsables de projets Open Source qui participent à Season of Docs. La priorité absolue du programme est de soutenir les projets en résolvant leurs problèmes avec la documentation.