À propos de Season of Docs
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 de se familiariser avec 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 documentations, consultez le site Web du programme.
Présentation du programme 2021
Modifications apportées au programme en 2021
En 2019 et 2020, les organisations et les rédacteurs techniques ont chacun postulé au programme Season of Docs séparément. Les rédacteurs techniques ont ensuite été mis en correspondance avec des organisations par les administrateurs du programme. Les entreprises ont fourni des mentors pour travailler avec les rédacteurs techniques, qui ont reçu une allocation pour leur travail en fonction de leur lieu de résidence. Le programme a mesuré si les rédacteurs techniques, les mentors et les administrateurs de l'organisation étaient satisfaits de leur participation au programme, mais n'a pas mesuré les résultats de la documentation.
En 2021, l'équipe de la saison de la documentation a apporté des modifications importantes 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.
- Les organisations ont envoyé des propositions de projets, y compris un budget et des métriques proposées.
- Les rédacteurs techniques ne passent plus par Google pour être mis en relation avec des organisations, mais s'adressent directement aux organisations acceptées.
- Les organisations acceptées ont reçu des subventions via Open Collective, qu'elles ont utilisées pour rémunérer des rédacteurs techniques.
- La rémunération des rédacteurs techniques était fixée par les organisations.
- Les organisations ont envoyé des évaluations et des études de cas finales, et répondu aux enquêtes de suivi.
Résultats généraux de 2021
Organisations
- Les changements apportés au programme en 2021 ont entraîné une diminution du nombre de candidatures (30% de moins en 2021 qu'en 2020), mais les administrateurs des organisations de 2021 étaient légèrement plus satisfaits du programme que ceux de 2020 (93% contre 91%).
Problèmes, types de documents et métriques
- La plupart des projets ont consisté à créer de la documentation pour réduire la charge des responsables (en réduisant le nombre de problèmes/questions) et/ou augmenter la participation au projet (par les utilisateurs ou les contributeurs).
- 50% des organisations acceptées ont créé des tutoriels ou des contenus de type "Comment faire".
- Plus de 50% des organisations acceptées ont estimé que leur documentation actuelle était insuffisante, désorganisée ou obsolète.
- Les projets visaient généralement à mesurer l'efficacité de leur documentation via les interactions, en particulier en réduisant le nombre de problèmes soulevés, en augmentant le nombre de visiteurs sur les documents et en favorisant la participation aux projets.
- En novembre 2022, 25 projets sur 30 ont répondu :
- 18 projets ont déclaré avoir atteint leurs métriques d'origine.
- 5 projets ont atteint 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 le paiement des rédacteurs techniques ont été la partie la plus difficile du programme pour les administrateurs d'organisations.
- En novembre 2022, 24 entreprises sur 30 ont répondu :
- 18 organisations collaboraient toujours avec leur rédacteur technique de la saison des documents (en tant que contributeur ou ressource pour répondre aux questions)
- 4 organisations ont travaillé avec leurs rédacteurs techniques de la saison de la documentation dans un rôle rémunéré
- 18 organisations collaboraient toujours avec leur rédacteur technique de la saison des documents (en tant que contributeur ou ressource pour répondre aux questions)
Faits marquants de 2021
- Plusieurs projets ont indiqué que leur rédacteur technique avait l'intention de continuer à travailler sur son projet après la fin du programme Season of Docs.
- Metanorma a reçu tellement de candidatures de rédacteurs techniques qualifiés qu'elle a trouvé des fonds correspondants pour embaucher un rédacteur supplémentaire pour travailler avec le rédacteur soutenu par la Saison des documents 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 de création de votre application.) La liste complète des organisations participantes est disponible sur le site Web de la saison des documents. 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 participantes à la Saison des documentations 2021 représentaient une grande variété 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 axés sur les développeurs, y compris des outils d'ingénierie du chaos, des fuzzers, des SDK de chatbot, des pipelines d'analyse de la composition logicielle, des outils de surveillance des performances et des outils de programmation visuelle
- Projets de documentation pour des outils de documentation, tels que Redocly et Metanorma
Les projets de l'écosystème Python représentaient la plus grande sous-catégorie. La cohorte 2021 comprenait ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite et SymPy.
Nous n'avons collecté aucune métadonnées sur les projets (date de création, répartition géographique des contributeurs, nombre de contributeurs ou taille de la base d'utilisateurs, par exemple).
Nous avons demandé aux projets d'indiquer la licence Open Source qu'ils utilisaient.
Les problèmes de documentation décrits par les organisations de 2021 sont très courants, à la fois 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 dans le cadre 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 la saison des documents 2021, qui contient des liens vers des études de cas complètes pour chaque organisation.
Types de documentation créés
Les tutoriels sont le type de documentation le plus fréquemment mentionné dans les études de cas de 2021.
Les autres types de documentation mentionnés dans les études de cas incluent les pipelines de documentation en tant que code, diagrammes, glossaires, guides de style, questions fréquentes, internationalisation, ateliers de programmation, modèles de contenu, modules, documentation de concepts, messages d'erreur, recherches sur l'expérience utilisateur, fichiers de lecture et bases de connaissances.
Certaines de ces catégories sont floues, et un même projet de documentation peut contenir plusieurs types ou fonctionnalités de documentation.
Plusieurs projets ont spécifiquement fait référence au framework Diátaxis comme guide pour planifier leurs types de documentation.
Pour en savoir plus, consultez la page des résultats de la saison des documents 2021, qui contient des liens vers des études de cas complètes pour chaque organisation.
Budgets
En 2021, le budget moyen demandé était de 10 200 $et la médiane de 10 000 $. Seules trois organisations ont demandé et reçu la subvention maximale possible (15 000 $), et trois autres ont demandé la subvention la plus faible possible (5 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 métriques les plus proposées étaient les suivantes:
D'autres métriques proposées incluaient les étoiles GitHub, le temps passé sur la page, les conversions de la liste de diffusion, les tests utilisateur qualitatifs, le nombre de participants aux forums, le nombre de partenaires/bénévoles/intégrations.
En raison du court laps de temps entre la fin des projets d'écriture technique et l'envoi des études de cas, la plupart des participants de la cohorte 2021 n'ont 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 la saison des documents 2021, qui contient des liens 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 façon dont les projets collaborent avec les rédacteurs techniques. Au cours des saisons précédentes, les rédacteurs techniques postulaient directement auprès de Google. Les administrateurs du programme les associaient à des projets et leur versaient une indemnité fixe directement de Google.
En 2021, les rédacteurs techniques ont postulé directement aux projets, qui ont défini le budget de rémunération des rédacteurs techniques. Les paiements ont été effectués via le fonds Open Collective de la saison des documents.
La plupart des projets participant au programme 2021 avaient peu ou pas d'expérience dans le recrutement ou l'embauche de rédacteurs techniques. De nombreux projets ont indiqué que cette partie du processus nécessitait plus d'aide. En réponse à ces commentaires, l'équipe de la saison des documents a ajouté au guide du programme une documentation pour créer des contrats de rédacteur technique.
Recommandations de recrutement
Les projets ont été invités à recommander d'autres projets intéressés par la participation à la Saison des documents. Voici les principales recommandations de recrutement:
- Partagez les documents de recrutement pour les rédacteurs techniques le plus tôt possible, même avant d'avoir été accepté dans le programme. Demandez à votre communauté de vous recommander des candidats potentiels.
- Partagez largement en dehors des canaux du projet. Utilisez un langage inclusif et encouragez directement les candidats issus de communautés sous-représentées à postuler.
- Identifiez les outils essentiels à votre processus de création de documentation et recrutez des rédacteurs techniques ayant l'expérience de ces outils.
- Définissez des attentes claires pour le rédacteur technique concernant les livrables et les jalons, les canaux de communication et les points de contrôle, ainsi que les processus et les délais de paiement.
- Envisagez d'investir dans les membres de la communauté et de les aider à se développer en tant que rédacteurs techniques en leur proposant un mentorat et un coaching grâce au programme de la saison de la documentation.
- Prévoyez plus de temps que prévu pour l'intégration des rédacteurs techniques, pour répondre à leurs questions et pour les aider tout au long du programme, en particulier s'ils n'ont aucune expérience dans le domaine de votre projet.
- Documentez votre processus de recrutement, d'embauche et d'intégration pour l'utiliser lors de futurs projets.
(Remarque: tous les projets indiqués dans leurs études de cas ne précisent pas où ils ont recruté leurs rédacteurs techniques.)
Problèmes courants liés à la collaboration avec des rédacteurs techniques
Les rédacteurs techniques de plusieurs projets ont dû abandonner 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 liés à des décalages de fuseau horaire ou à des problèmes de connectivité Internet.
Les projets ont constaté qu'ils avaient sous-estimé les difficultés liées à l'intégration dans leurs communautés ou à la configuration de la chaîne d'outils de documentation de leur projet.
Le paiement des rédacteurs techniques de certains projets a été retardé en raison de problèmes bancaires avec Open Collective ou de restrictions de paiement dans le pays de résidence des rédacteurs.
La documentation du programme concernant les frais Open Collective n'était pas claire: Google couvrait les frais de transaction Open Collective pour le transfert initial de fonds vers les projets, mais pas les frais de transaction imposés par d'autres canaux de paiement (comme les frais de conversion de devise). Nous ferons de notre mieux pour clarifier ce point 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 (déterminée par les métriques qu'ils ont définies dans leur étude de cas), ainsi que sur la participation et la rémunération continues des rédacteurs techniques du projet:
- Continuez-vous à travailler avec votre rédacteur technique de la saison des documents ?
- Si votre rédacteur technique travaille toujours sur votre projet, est-il rémunéré ?
- À ce stade, pensez-vous que votre projet de documentation est réussi ?
Questions futures
Comme toujours, plus nous en apprenons sur la documentation Open Source, plus nous voulons en savoir ! Dans les prochaines saisons, nous espérons apprendre:
- Indique si les domaines de projet sont corrélés au choix du type de document ou des métriques
- Les pratiques de recrutement et d'intégration des rédacteurs techniques les plus efficaces pour la réalisation des projets et la fidélisation des rédacteurs techniques
- Délais raisonnables pour mesurer l'efficacité de la documentation
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.