Phase actuelle:
Développement de la documentation. Consultez le calendrier.
Season of Docs est un programme de développement durable géré par le Google Open Source Programs Office. Voici les objectifs de Season of Docs:
- Fournir de la documentation pour soutenir les projets Open Source afin de résoudre les problèmes des projets
- 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
- Collecter et partager 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 2022
Fonctionnement de Season of Docs
Dans Season of Docs, les organisations postulent en soumettant une proposition de projet. La proposition de projet comprend:
- Informations sur l'organisation
- Une description du problème auquel le projet est confronté
- Comment le projet utilisera la documentation pour aider à résoudre son problème
- La manière dont le projet mesurera l'efficacité de sa documentation (métriques)
- Un calendrier des travaux
- Un budget de projet
- Toute information supplémentaire, telle que l'expérience de l'organisation dans des programmes similaires, ou toute autre information susceptible d'aider les administrateurs de la saison des documents à comprendre leur projet et leur problème
Une fois acceptées dans le programme, les entreprises recrutent et embauchent directement leurs propres rédacteurs techniques. 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. Ils sont inclus dans les propositions de projets de l'organisation disponibles sur le site Season of Docs, et les paiements sont visibles dans le compte Open Collective de Season of Docs.
Les organisations sont considérées comme ayant terminé le programme avec succès lorsqu'elles soumettent leur rapport d'étude de cas. Les organisations sont également invitées à réaliser des évaluations mensuelles pendant le programme et trois enquêtes de suivi trimestrielles au cours de l'année suivant la fin du programme.
Temps forts de 2022
"Après la publication du nouveau document, le nombre de visites quotidiennes à Casbin et Casdoor a presque doublé, et les taux de rebond ont chuté d'environ 30%." – Casbin
"Ce projet a été concluant : nous avons vu [nos rédacteurs techniques] devenir des leaders dans notre communauté. Les deux contributeurs dirigent désormais des groupes de travail et des réunions de la communauté, tout en contribuant à 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 standard, qui restent des contributeurs actifs de système d'exploitation pour OpenMined et avec lesquels nous avons eu une excellente expérience professionnelle." – OpenMined
"De plus, le nouveau manuel est beaucoup plus facile pour les débutants en matière de spectrométrie de masse computationnelle. Pour illustrer ce point: la subvention CZI fournit également des aides à des personnes historiquement défavorisées. Certains bénéficiaires ont utilisé le nouveau manuel OpenMS pour commencer leur période de stage de six semaines et ont donné des avis positifs sur le nouveau manuel." – OpenMS
Données récapitulatives 2022
En 2022, le programme Season of Docs a accepté 31 projets sur 67 candidatures, et 30 projets l'ont terminé avec succès. Sur les 31 organisations acceptées, 17 organisations ont postulé plusieurs fois.
Les 31 projets acceptés ont embauché 58 rédacteurs techniques. Plus de 190 rédacteurs techniques ont indiqué leur souhait de participer au programme en ajoutant leurs coordonnées et des liens vers leurs portfolios dans le dépôt GitHub Season of Docs.
Pour le programme 2022:
- 100% des entreprises ont eu une expérience positive du processus de candidature
- 100% des organisations ont eu une expérience positive de la documentation/du contenu du site Web du programme.
- 93% des organisations ont vécu une expérience positive du programme.
- 90% des organisations ont estimé que leur projet de documentation était efficace
À propos des organisations
Les organisations participant à Season of Docs 2022 représentaient une large gamme de projets Open Source. La cohorte 2022 comprenait:
- Des outils de développement, tels qu'AsyncAPI et SpyderIDE
- Langages et frameworks de programmation tels que Julia, LFortran, R et p5.js
- Projets scientifiques tels que le CERN-HSF et SymPy
- Les applications pour les utilisateurs finaux, telles que Mautic, Open Food Facts, Talawa et Ushahidi
- Projets matériels et robotiques, tels qu'ExpressLRS et Open-RMF
- Projets de données, tels que GeomScale, GeomStats, OpenMined et Weaviate
- Projets cloud et d'infrastructure, tels que cert-manager, NimbleEdge et Cilium
Nous n'avons pas collecté de métadonnées sur les projets (comme 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 quelle licence Open Source ils utilisaient.
À propos des projets de documentation
Problèmes de documentation
Voici les principaux problèmes que les organisations espéraient résoudre à l'aide de la documentation pour le programme 2022:
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 2022, qui renvoie vers les propositions de projets originales et les études de cas complètes de chaque organisation.
Types de documents 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 documents mentionnés dans les études de cas:
- Guide de démarrage rapide
- Glossaire
- Questions fréquentes
- Base de connaissances
- Composants
- Blogs et contenus de réseaux sociaux
- Guide de l'utilisateur
Certaines de ces catégories sont floues et un seul projet de documentation peut contenir plusieurs types de documentation ou fonctionnalités.
Pour en savoir plus, consultez la page des résultats de Season of Docs 2022, qui renvoie vers les propositions de projets originales et les études de cas complètes de chaque organisation.
Budgets
La demande de budget moyen était de 11 679 $et la médiane de 12 150 $. Cinq d'entre elles ont demandé et reçu la subvention la plus élevée disponible (15 000 $), et trois d'entre elles ont demandé la plus faible (entre 5 000 et 7 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:
Voici d'autres métriques proposées:
- Demandes d'extraction/contributions supplémentaires
- Commentaires plus directs sur les pages de documentation
- Temps passé sur la page
- Problèmes soulevés (en tant que proxy pour l'utilisation)
- Participants aux forums
- Nombre de partenaires/bénévoles/intégrations
- Taux de rebond réduit
- Une sensibilisation accrue au sein de la communauté.
En raison du court laps de temps entre la fin des projets de rédaction technique et la soumission des études de cas, la plupart des membres de la cohorte 2022 n'avaient pas pu collecter suffisamment de données au moment de soumettre leurs études de cas pour déterminer si leurs métriques initiales avaient été atteintes ou non.
Au fur et à mesure que nous recevrons des 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 révisé leurs métriques.
Pour en savoir plus, consultez la page des résultats de Season of Docs 2022, qui renvoie vers les propositions de projets originales et les études de cas complètes de chaque organisation.
Travailler avec des rédacteurs techniques
Au cours de la saison des documents, les projets doivent recruter, interviewer, embaucher et payer directement les rédacteurs techniques. Les rédacteurs techniques peuvent s'ajouter eux-mêmes au répertoire géré par Season of Docs dans notre dépôt GitHub, mais l'équipe Season of Docs n'examine pas ni ne recommande les rédacteurs techniques.
Bonnes pratiques de recrutement de rédacteurs techniques pour les projets Open Source
Les projets ont été invités à partager leurs meilleures pratiques en matière de recrutement, d'embauche et de travail avec les rédacteurs techniques. Voici les principales recommandations:
Recrutement
- Faites passer des entretiens avec moins de candidats et utilisez une session d'entraînement en direct plutôt que de vous contenter d'examiner les CV
- Valoriser les compétences en communication écrite et orale plutôt que la maîtrise du langage ou des outils de votre projet
- Posez des questions directes sur la manière dont le rédacteur technique acquiert les connaissances du domaine nécessaires pour travailler avec votre projet
- Une personne qui s'enthousiasme pour 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
- Soyez ouvert aux candidats du monde entier, car une diversité de points de vue et d'origines contribuera à votre projet, mais gardez à l'esprit que la présence d'auteurs et de mentors dans un trop grand nombre de fuseaux horaires peut nécessiter beaucoup d'efforts supplémentaires pour maintenir une bonne communication.
Nombre de collaborateurs recherchés
- Utilisez un contrat qui indique clairement les produits livrables, les échéanciers de paiement et les engagements de temps spécifiques
- Si votre projet comporte beaucoup d'inconnues, incluez un jalon de découverte ou de recherche distinct de la création de la documentation.
Coordination et communication
- Tenez un journal de réunion pour enregistrer les décisions prises afin de permettre à toutes les personnes travaillant sur le projet de comprendre le contexte et les prochaines étapes.
- Soyez clair sur les communications attendues et à quelle fréquence, qu'il s'agisse d'appels hebdomadaires, d'e-mails quotidiens ou de mises à jour de statut dans un canal de chat.
- Soyez réactif et donnez un feedback clair en incluant le « pourquoi » et pas seulement « quoi ».
- Mettre en relation vos rédacteurs techniques avec l'ensemble de la communauté pour leur donner du contexte et partager leur travail sur les réseaux sociaux
Processus et outils
- Créer un processus de documentation qui s'étendra au-delà de la saison des documents Google et auquel toute la communauté pourra contribuer
- L'examen de la documentation prendra au moins autant de temps et est tout aussi intensif que l'examen de code ; assurez-vous de lui laisser suffisamment de temps
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 saison 2022 ont postulé directement auprès des organisations avec lesquelles ils travaillaient.
Problèmes courants lors de 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. L’incapacité des rédacteurs techniques à terminer le programme était le problème le plus important, en raison d’une maladie, d’un emploi à temps plein ou de l’incapacité de respecter les délais.
Selon un projet, leur projet de documentation dépendait du travail effectué dans le cadre de Google Summer of Code, et ces dépendances étaient difficiles à gérer. Un autre projet a rencontré des difficultés lorsque le matériel que leur rédacteur technique avait besoin pour documenter a été confisqué par le ministère de la Défense du pays de l'écrivain et n'a pas pu être importé.
Enquêtes de suivi
Trois enquêtes de suivi seront envoyées aux participants 2022 en mai, août et novembre 2023. Nous mettrons à jour cette section avec les résultats au fur et à mesure de leur réception.
Questions futures
Comme toujours, plus nous apprenons sur la documentation en open source, plus nous voulons en apprendre !
Au cours des prochaines saisons, nous espérons:
- Collecter plus de métadonnées du projet pour rechercher des corrélations entre l’âge du projet, la taille de la communauté ou les besoins en termes de langue et de documentation
- Analyser les projets de documentation pour voir s'ils peuvent être généralisés dans des modèles partageables
- Élaborer une grille d’évaluation pour les entretiens de rédacteurs techniques dans des projets open source
Bien qu'il existe de nombreuses 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 grâce à la documentation.