Phase actuelle:
Études de cas publiées. Voir la chronologie.
La saison des documentations est un programme de développement durable géré par l'équipe Open Source Programs de Google. Les objectifs de Season of Docs sont les suivants:
- Fournir une assistance aux projets Open Source pour résoudre les problèmes de projet à l'aide de la documentation
- Offrir aux rédacteurs techniques l'occasion d'acquérir de l'expérience dans le domaine de l'Open Source
- Sensibiliser les utilisateurs à l'Open Source, à la documentation et à l'écriture technique
- Collecter et partager des informations sur les métriques efficaces dans la documentation Open Source
Pour en savoir plus sur la saison des documentaires, consultez le site Web du programme.
Présentation du programme 2022
Fonctionnement de Season of Docs
Lors de la Saison des documents, les organisations doivent envoyer une proposition de projet pour participer. La proposition de projet comprend les éléments suivants:
- Informations sur l'organisation
- Une description du problème auquel le projet est confronté
- Comment la documentation aidera-t-elle à résoudre le problème ?
- Comment le projet mesurera-t-il l'efficacité de sa documentation (métriques) ?
- Un calendrier pour le travail
- Un budget de projet
- Toute information supplémentaire, comme l'expérience de l'organisation dans des programmes similaires ou tout autre élément qui pourrait aider les administrateurs de la saison des documents à comprendre leur projet et leur problème
Une fois acceptés 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 les organisations 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 projets d'organisation disponibles sur le site de la Saison des documents, et les paiements sont visibles dans le compte Open Collective de la Saison des documents.
Les organisations sont considérées comme ayant terminé le programme lorsqu'elles envoient leur rapport d'étude de cas. Les organisations sont également invitées à remplir des évaluations mensuelles pendant le programme et trois enquêtes de suivi trimestrielles au cours de l'année suivant la fin du programme.
Faits marquants de 2022
"Après la publication du nouveau document, le nombre de visites quotidiennes sur Casbin et Casdoor a presque doublé, et les taux de rebond ont chuté d'environ 30%." – Casbin
"L'un des résultats positifs de ce projet a été de voir [nos rédacteurs techniques] occuper des rôles de leadership au sein de notre communauté. Les deux contributeurs dirigent désormais des réunions de groupe de travail et de la communauté, et participent à 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. Ils continuent d'être des contributeurs actifs à OpenMined et nous avons eu une excellente expérience de travail avec eux." – OpenMined
"De plus, le nouveau manuel est beaucoup plus facile à comprendre pour les débutants en spectrométrie de masse computationnelle. Pour illustrer ce point, la subvention de la CZI fournit également des bourses aux personnes historiquement défavorisées. Certains bénéficiaires ont utilisé le nouveau manuel OpenMS pour lancer leur stage de six semaines et ont donné des avis positifs sur ce nouveau manuel." – OpenMS
Données récapitulatives de 2022
En 2022, le programme Season of Docs a accepté 31 projets parmi 67 candidatures, et 30 projets ont terminé le programme. Sur les 31 organisations acceptées, 17 avaient déjà fait une demande.
Les 31 projets acceptés ont permis d'embaucher 58 rédacteurs techniques. Plus de 190 rédacteurs techniques ont indiqué leur intérêt à participer au programme en ajoutant leurs coordonnées et des liens vers leurs portfolios dans le dépôt GitHub de la saison de la documentation.
Pour le programme 2022:
- 100% des organisations ont eu une expérience positive avec le processus de candidature
- 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 participantes à la saison des documentations 2022 représentaient une grande variété de projets Open Source. La cohorte 2022 comprenait les éléments suivants:
- Outils de développement, tels que AsyncAPI et SpyderIDE
- Langages et frameworks de programmation, tels que Julia, LFortran, R et p5.js
- Projets scientifiques, tels que CERN-HSF et SymPy
- Applications pour utilisateurs finaux, telles que Mautic, Open Food Facts, Talawa et Ushahidi
- Projets matériels et robotiques, tels que 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 collecté aucune 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 la licence Open Source qu'ils utilisaient.
À propos des projets de documentation
Problèmes liés à la documentation
Voici les principaux problèmes que les organisations espéraient résoudre grâce à la documentation dans le cadre du programme de 2022:
Notez que les organisations peuvent signaler plusieurs problèmes de documentation. Pour en savoir plus, consultez la page des résultats de la saison de la documentation 2022, qui contient des liens vers les propositions de projets d'origine et les études de cas complètes de chaque organisation.
Types de documentation créés
Les documents de procédure ont été le type de documentation le plus fréquemment 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/réseaux sociaux
- Guide du mainteneur
Certaines de ces catégories sont floues, et un même projet de documentation peut contenir plusieurs types ou fonctionnalités de documentation.
Pour en savoir plus, consultez la page des résultats de la saison de la documentation 2022, qui contient des liens vers les propositions de projets d'origine et les études de cas complètes de chaque organisation.
Budgets
Le budget moyen demandé é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 faible (entre 5 000 $et 7 000 $).
Statistiques
Les projets décrits dans leurs études de cas ont indiqué les métriques qu'ils utilisaient pour évaluer la réussite de leurs projets de documentation.
Les principales métriques proposées étaient les suivantes:
Voici d'autres métriques proposées:
- Plus de demandes de tirage/contributions de documentation
- Commentaires plus directs sur les pages de documentation
- Temps passé sur la page
- Problèmes soulevés (proxy de l'utilisation)
- Participants aux forums
- Nombre de partenaires/volontaires/intégrations
- Taux de rebond réduit
- Une meilleure sensibilisation au sein de la communauté
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 2022 n'ont 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 saison de la documentation 2022, qui contient des liens vers les propositions de projets d'origine et les études de cas complètes de chaque organisation.
Travailler avec des rédacteurs techniques
Dans le cadre du programme Season of Docs, les projets doivent recruter, interroger, embaucher et payer directement des rédacteurs techniques. Les rédacteurs techniques peuvent s'ajouter au répertoire géré par Season of Docs dans notre dépôt GitHub, mais le personnel de Season of Docs ne vérifie ni ne recommande les rédacteurs techniques.
Bonnes pratiques pour l'embauche de rédacteurs techniques pour des projets Open Source
Les projets ont été invités à partager leurs bonnes pratiques de recrutement, d'embauche et de collaboration avec des rédacteurs techniques. Voici les principales recommandations:
Recrutement
- Menez moins d'entretiens et organisez une session d'entraînement en direct plutôt que de simplement examiner des CV.
- Privilégiez les compétences en communication écrite et orale plutôt que la maîtrise de la langue ou des outils de votre projet
- Posez des questions directes sur la façon dont le rédacteur technique acquerra les connaissances nécessaires pour travailler sur votre projet.
- Une personne qui est 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.
- Soyez ouvert aux candidats du monde entier, car la diversité des points de vue et des parcours contribuera à votre projet. Toutefois, gardez à l'esprit que la présence d'auteurs et de mentors dans trop de fuseaux horaires différents peut nécessiter beaucoup d'efforts supplémentaires pour maintenir une bonne communication.
Nombre de collaborateurs recherchés
- Utilisez un contrat qui définit clairement les livrables, les échéanciers de paiement et les délais spécifiques.
- Si votre projet comporte de nombreuses inconnues, incluez un jalon de découverte ou de recherche distinct de la création de documentation.
Coordination et communication
- Tenez un journal de réunion pour enregistrer les décisions afin que toutes les personnes impliquées dans le projet puissent comprendre plus facilement le contexte et les prochaines étapes.
- Indiquez clairement les communications attendues et leur fréquence, qu'il s'agisse d'appels hebdomadaires, d'e-mails quotidiens ou de mises à jour de l'état dans un canal de chat.
- Soyez réactif et donnez des commentaires clairs qui incluent le "pourquoi" et pas seulement le "quoi".
- Mettez vos rédacteurs techniques en relation avec la communauté plus large pour leur donner du contexte et faire connaître leur travail.
Processus et outils
- Créer un processus de documentation qui s'étendra au-delà du programme Saison de la documentation et auquel toute la communauté pourra contribuer
- L'examen de la documentation prendra au moins autant de temps et sera tout aussi intensif que l'examen du code. Prévoyez suffisamment de temps pour cela.
Certaines recommandations ont été modifiées et condensées pour plus de clarté.
Comme lors du programme de 2021, la plupart des rédacteurs techniques de la saison des documents 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 de 2022. Le plus grand problème était que les rédacteurs techniques ne pouvaient pas terminer le programme, en raison d'une maladie, d'un emploi à temps plein ou de l'impossibilité de respecter l'engagement temporel.
Un projet a indiqué que son projet de documentation dépendait du travail effectué 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 le rédacteur technique devait documenter a été confisqué par le ministère de la Défense du pays dans lequel il se trouvait et qu'il ne pouvait pas ê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 au fur et à mesure que nous recevrons les résultats.
Questions futures
Comme toujours, plus nous en apprenons sur la documentation Open Source, plus nous voulons en savoir !
Pour les prochaines saisons, nous espérons:
- Collecter plus de métadonnées de projet pour rechercher des corrélations entre l'âge du projet, la taille de la communauté ou les besoins en langue et 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 les entretiens avec des rédacteurs techniques dans des projets Open Source
Bien que nous souhaitions répondre à de nombreuses questions, nous voulons aussi respecter le temps des administrateurs et des responsables de projets Open Source qui participent à la Saison des documentations. La priorité absolue du programme est d'aider les projets à résoudre leurs problèmes grâce à la documentation.