La Season of Docs est un programme de développement durable géré par l'équipe Open Source Programs de Google. Les objectifs de la Season of Docs sont les suivants :
- Fournir une assistance aux projets Open Source pour résoudre les problèmes de projet liés à la documentation
- Offrir 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
- Collecter et partager des informations sur les métriques efficaces dans la documentation Open Source
Pour en savoir plus sur la Season of Docs, consultez le site Web du programme.
Présentation du programme 2022
Fonctionnement de la Season of Docs
Lors de la Season of Docs, les organisations envoient une proposition de projet. Cette proposition comprend les éléments suivants :
- Informations sur l'organisation
- Description du problème rencontré par le projet
- Comment le projet utilisera la documentation pour résoudre son problème
- Comment le projet mesurera l'efficacité de sa documentation (métriques)
- Chronologie des travaux
- Budget du projet
- Toute information supplémentaire, telle que l'expérience de l'organisation dans des programmes similaires ou tout autre élément qui aiderait les administrateurs de la Season of Docs à comprendre leur projet et leur problème
Une fois acceptées dans le programme, les organisations recrutent et embauchent directement leurs propres rédacteurs techniques. La Season of Docs utilise Open Collective pour financer les organisations, et celles-ci paient les rédacteurs techniques via Open Collective. Les budgets et les paiements des projets sont transparents. Les budgets sont inclus dans les propositions de projet des organisations disponibles sur le site de la Season of Docs, et les paiements sont visibles dans le compte Open Collective de la Season of Docs.
Les organisations sont considérées comme ayant terminé le programme avec succès lorsqu'elles envoient leur rapport d'étude de cas. Elles sont également invitées à effectuer des évaluations mensuelles pendant le programme et trois enquêtes de suivi trimestrielles au cours de l'année suivant la fin du programme.
Points forts de 2022
"Après la publication du nouveau document, les visites quotidiennes de Casbin et Casdoor ont presque doublé, et les taux de rebond ont diminué d'environ 30%." – Casbin
"L'un des résultats les plus agréables de ce projet a été de voir [nos rédacteurs techniques] devenir des leaders dans notre communauté. Les deux contributeurs animent désormais des réunions de groupes de travail et de la communauté, et contribuent à la conception et à la maintenance de nos projets." – moja-global
"[GSoD] nous a aidés à recruter deux rédacteurs techniques talentueux, ce qui est très difficile dans une configuration classique. Ils continuent d'être des contributeurs OS actifs pour OpenMined, et nous avons eu une excellente expérience de travail avec eux." – OpenMined
"De plus, le nouveau manuel est beaucoup plus facile à utiliser pour les débutants en spectrométrie de masse computationnelle. Pour illustrer ce point : la subvention CZI fournit également des allocations aux personnes historiquement défavorisées, et certains bénéficiaires ont utilisé le nouveau manuel OpenMS pour démarrer leur stage de six semaines et ont donné des avis positifs sur le nouveau manuel." – OpenMS
Données récapitulatives de 2022
En 2022, le programme Season of Docs a accepté 31 projets sur 67 demandes, et 30 projets ont été menés à bien. Parmi les 31 organisations acceptées, 17 avaient déjà postulé.
Les 31 projets acceptés ont embauché 58 rédacteurs techniques. Plus de 190 rédacteurs techniques ont indiqué qu'ils souhaitaient participer au programme en ajoutant leurs coordonnées et des liens vers leurs portfolios dans le dépôt GitHub de la Season of Docs.
Pour le programme 2022 :
- 100% des organisations ont eu une expérience positive avec le processus de demande
- 100% des organisations ont eu une expérience positive avec la documentation/le contenu du site Web du programme
- 93% des organisations ont eu une expérience positive avec le programme
- 90% des organisations ont estimé que leur projet de documentation avait été un succès
À propos des organisations
Les organisations participant à la Season of Docs 2022 représentaient un large éventail de projets Open Source. La cohorte 2022 comprenait :
- Des outils de développement, tels que AsyncAPI et SpyderIDE
- Des langages et frameworks de programmation, tels que Julia, LFortran, R, et p5.js
- Des projets scientifiques, tels que CERN-HSF et SymPy
- Des applications pour les utilisateurs finaux, telles que Mautic, Open Food Facts, Talawa, et Ushahidi
- Des projets matériels et robotiques, tels que ExpressLRS et Open-RMF
- Des projets de données, tels que GeomScale, GeomStats, OpenMined, et Weaviate
- Des projets cloud et d'infrastructure, tels que cert-manager, NimbleEdge, et Cilium
Nous n'avons collecté aucune métadonnée 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.
À propos des projets de documentation
Problèmes de documentation
Les principaux problèmes que les organisations espéraient résoudre grâce à la documentation dans le programme 2022 étaient les suivants :
Notez que les organisations pouvaient signaler plusieurs problèmes de documentation. Pour en savoir plus, consultez la page des résultats de la Season of Docs 2022, qui contient des liens vers les propositions de projet d'origine et les études de cas complètes pour chaque organisation.
Types de documentation créés
La documentation pratique était le type de documentation le plus souvent mentionné dans les études de cas de 2022.
Voici d'autres types de documentation mentionnés dans les études de cas :
- Guide de démarrage rapide
- Glossaire
- Questions fréquentes
- Base de connaissances
- Composants
- Contenu de blog/de réseaux sociaux
- Guide du mainteneur
Certaines de ces catégories sont floues, et un seul projet de documentation peut contenir plusieurs types ou fonctionnalités de documentation.
Pour en savoir plus, consultez la page des résultats de la Season of Docs 2022, qui contient des liens vers les propositions de projet d'origine et les études de cas complètes pour chaque organisation.
Budgets
La demande de budget moyenne était de 11 679 $, et la médiane de 12 150 $. Cinq organisations ont demandé et reçu la subvention la plus élevée disponible (15 000 $), et trois ont demandé la plus basse (entre 5 000 et 7 000 $).
Statistiques
Dans leurs études de cas, les projets ont décrit les métriques qu'ils utilisaient pour évaluer le succès de leurs projets de documentation.
Les principales métriques proposées étaient les suivantes :
Voici d'autres métriques proposées :
- Plus de demandes d'extraction/de contributions à la documentation
- Plus de commentaires directs sur les pages de documentation
- Temps passé sur la page
- Problèmes signalés (en tant que proxy d'utilisation)
- Participants aux forums
- Nombre de partenaires/bénévoles/intégrations
- Taux de rebond réduit
- Sensibilisation accrue dans la communauté
En raison du court délai entre la fin des projets de rédaction technique et l'envoi des études de cas, la plupart des participants de la cohorte 2022 n'avaient pas pu collecter suffisamment de données au moment de l'envoi de leurs études de cas pour déterminer si leurs métriques initiales avaient été atteintes ou non.
À mesure que nous recevrons les réponses aux enquêtes de suivi en 2023, nous mettrons à jour ce rapport pour ajouter des informations sur les projets qui ont atteint leurs métriques ou les ont révisées.
Pour en savoir plus, consultez la page des résultats de la Season of Docs 2022, qui contient des liens vers les propositions de projet d'origine et les études de cas complètes pour chaque organisation.
Travailler avec des rédacteurs techniques
Dans le programme Season of Docs, les projets doivent recruter, interviewer, embaucher et payer directement les rédacteurs techniques. Les rédacteurs techniques peuvent s'ajouter à l'annuaire géré par la Season of Docs dans notre dépôt GitHub, mais le personnel de la Season of Docs ne vérifie ni ne recommande les rédacteurs techniques.
Bonnes pratiques pour embaucher des rédacteurs techniques pour des projets Open Source
Les projets ont été invités à partager leurs bonnes pratiques en matière de recrutement, d'embauche et de collaboration avec des rédacteurs techniques. Voici les principales recommandations :
Recrutement
- Interviewer moins de candidats et utiliser une session de pratique en direct plutôt que de simplement examiner les CV
- Valoriser les compétences en communication écrite et orale plutôt que la maîtrise de la langue ou des outils de votre projet
- Poser des questions directes sur la façon dont le rédacteur technique acquerra les connaissances du domaine nécessaires pour travailler sur votre projet
- Une personne enthousiaste à l'égard de la mission de votre projet et qui partage les valeurs fondamentales de l'Open Source est plus susceptible de rester motivée tout au long du projet
- Être ouvert aux candidats du monde entier, car la diversité des points de vue et des parcours aidera votre projet. Toutefois, veillez à ce que les rédacteurs et les mentors ne soient pas dans trop de fuseaux horaires conflictuels, car cela pourrait nécessiter beaucoup d'efforts supplémentaires pour maintenir une bonne communication
Embauche
- Utiliser un contrat qui indique clairement les produits livrables, les calendriers de paiement et les engagements de temps spécifiques
- Si votre projet comporte de nombreuses inconnues, incluez une étape de découverte ou de recherche distincte de la création de la documentation
Coordination et communication
- Tenir un journal des réunions pour enregistrer les décisions afin que tous les membres de l'équipe travaillant sur le projet puissent comprendre le contexte et les prochaines étapes
- Indiquer clairement le type de communication attendu et sa fréquence (appels hebdomadaires, e-mails quotidiens ou mises à jour de l'état dans un canal de discussion, par exemple)
- Être réactif et fournir des commentaires clairs qui incluent le "pourquoi" et pas seulement le "quoi"
- Mettre en relation vos rédacteurs techniques avec la communauté au sens large pour leur donner du contexte et faire connaître leur travail
Processus et outils
- Créer un processus de documentation qui durera au-delà du programme Season of Docs et auquel l'ensemble de la communauté pourra contribuer
- L'examen de la documentation prendra au moins autant de temps et sera tout aussi intensif que la revue de code. Assurez-vous de prévoir suffisamment de temps pour cela.
Certaines recommandations ont été modifiées et condensées pour plus de clarté.
Comme pour le programme 2021, la plupart des rédacteurs techniques de la Season of Docs 2022 ont postulé directement auprès des organisations avec lesquelles ils ont travaillé.
Problèmes courants liés à la collaboration avec des rédacteurs techniques
Moins de projets ont signalé des problèmes de collaboration avec leurs rédacteurs techniques dans le programme 2022. Le principal problème était l'incapacité des rédacteurs techniques à terminer le programme en raison d'une maladie, d'un emploi à temps plein ou d'un manque de temps.
Un projet a signalé que son projet de documentation dépendait de travaux effectués dans le cadre du Google Summer of Code et que ces dépendances étaient difficiles à gérer. Un autre projet a rencontré des difficultés lorsque le matériel que son rédacteur technique devait documenter a été confisqué par le ministère de la Défense dans le pays du rédacteur et n'a pas pu être importé.
Enquêtes de suivi
Trois enquêtes de suivi seront envoyées aux participants de 2022 en mai, août et novembre 2023. Nous mettrons à jour cette section avec les résultats à mesure qu'ils seront reçus.
Questions futures
Comme toujours, plus nous en apprenons sur la documentation dans l'Open Source, plus nous voulons en savoir plus !
Lors des prochaines saisons, nous espérons :
- Collecter davantage de métadonnées de projet pour rechercher des corrélations entre l'ancienneté du projet, la taille de la communauté ou la langue et les besoins en documentation
- Analyser les projets de documentation pour voir s'ils peuvent être généralisés en modèles partageables
- Élaborer une grille d'évaluation pour interviewer les rédacteurs techniques dans les projets Open Source
Bien que nous ayons de nombreuses questions à étudier, nous souhaitons également respecter le temps des administrateurs et des mainteneurs de projets Open Source qui participent à la Season of Docs. La priorité absolue du programme est d'aider les projets à résoudre leurs problèmes de documentation.