Phase actuelle:
La saison 2021 du programme Docs s'est terminée le 14 décembre 2021. Voir la chronologie.
Utilisez cet exemple pour vous aider à créer votre propre rapport d'étude de cas.
PicklePlus: documenter l'outil de contribution GloriousPickle
Organisation ou projet: Glorious Pickle lien vers le site principal de votre organisation ou de votre projet
Description de l'organisation: GloriousPickle (version actuelle 1.2.3, première version en 2009) est une bibliothèque sous licence MIT qui permet de calculer facilement le ratio parfait de sel, de sucre, de vinaigre et d'épices pour tous les légumes pouvant être marinés, en quantités allant d'un seul concombre miniature à des cargaisons de radis.
Auteurs: facultatif: listez les auteurs de l'étude de cas ; utilisez des noms d'utilisateur si nécessaire
Énoncé du problème/Résumé de la proposition
Quel problème essayiez-vous de résoudre avec une nouvelle documentation ou une documentation améliorée ? Si possible, ajoutez un lien vers la page de la proposition sur le site de votre projet.
L'ajout d'ingrédients à la base de données d'ingrédients de l'outil GloriousPickle est long et compliqué, et l'outil ne dispose pas d'une bonne documentation. De nombreux contributeurs potentiels n'ont pas d'expérience avec Git ni avec les requêtes pull. Cela signifie que GloriousPickle présente de sérieuses lacunes dans nos données d'ingrédients, ce qui rend notre outil moins utile. En améliorant la documentation sur l'ajout de nouveaux ingrédients, nous espérons encourager de nouveaux contributeurs et plus de pickling !
Description du projet
Créer la proposition
Comment avez-vous imaginé votre proposition pour la période des fêtes de fin d'année ? Quel processus votre organisation a-t-elle suivi pour choisir une idée ? Comment avez-vous recueilli et intégré les commentaires ?
Le groupe de discussion PickleDocs de GloriousPickle a entendu parler du programme Season of Docs via un tweet de l'équipe Open Source Programs de Google. Le groupe de discussion a discuté du programme lors de sa réunion bimensuelle et a accepté de créer une proposition. Deux membres du SIG (@KimChiCook et @Dillicious) se sont portés volontaires pour travailler sur le brouillon de la proposition afin de l'examiner lors de la prochaine réunion.
Une fois que le groupe de travail PickleDocs a approuvé le brouillon de la proposition, un e-mail a été envoyé à l'ensemble du projet pour recueillir des commentaires. Quatorze membres de la communauté ont envoyé des commentaires, dont @GloriousPicklePat, le responsable de l'API d'ajout d'ingrédients. @GloriousPicklePat s'est porté volontaire pour être une ressource pendant le programme.
Après avoir discuté des commentaires reçus et les avoir intégrés, la proposition a été envoyée au comité directeur du projet GloriousPickle pour un vote. Les cinq membres du GPPSC ont voté "+1" pour envoyer la proposition et la demande, et @VinegarViv a accepté de nous aider à créer le compte Open Collective requis pour participer au programme et superviser les paiements.
Budget
Précisez brièvement votre budget. Comment avez-vous estimé le travail ? Y a-t-il eu des dépenses imprévues ? Avez-vous dépensé moins que le montant de la subvention ? Avez-vous pu utiliser d'autres fonds en dehors de la saison des documents ?
Deux membres du groupe de travail PickleDocs de GloriousPickle ont travaillé en tant que rédacteurs techniques (l'un en Europe et l'autre en Argentine). Ils nous ont aidés à estimer le travail et à trouver des budgets de projets similaires, en comparant le travail de la proposition préliminaire qu'ils avaient effectué précédemment. Nous avions également 1 000$de fonds de sponsoring non limités restants de notre convention PicklePals 2019 que nous avons alloués au projet.
Une dépense imprévue a été d'aider notre rédacteur technique à louer un point d'accès Wi-Fi, car il se trouvait dans une zone touchée par des feux de forêt et avait perdu l'accès à Internet chez lui. Nous avons également fini par envoyer moins de T-shirts aux participants que prévu, donc le résultat a été équilibré.
De plus, nous avons décidé de rémunérer un contributeur de GloriousPickle, @Piccalily (qui était rédactrice professionnelle dans sa vie d'avant les cornichons) pour l'aider à corriger et à relire la documentation créée par le rédacteur technique.
Participants
Qui a travaillé sur ce projet (utilisez les noms d'utilisateur si les participants le demandent) ? Comment avez-vous trouvé et embauché votre rédacteur technique ? Comment avez-vous trouvé d'autres bénévoles ou participants rémunérés ? Quels rôles avaient-ils occupés ? Quelqu'un a-t-il abandonné ? Qu'avez-vous appris sur le recrutement, la communication et la gestion de projet ?
L'équipe de base qui a travaillé sur ce projet était:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (aide pour les administrateurs, GPPSC)
- @BBChips, @GloriousPicklePat (experts du domaine)
- Sam Scribe (rédacteur technique)
Nous avons trouvé Sam Scribe dans la liste du dépôt GitHub de la saison des documentations. Nous avons pensé que son expérience (Sam avait travaillé pour un magazine culinaire et rédigé de la documentation pour des sites Web) correspondait bien à notre projet. Sam a rejoint l'appel bimensuel du groupe de travail PickleDocs et nous a parlé du projet. Il nous a fait plusieurs suggestions très utiles que nous avons intégrées à la proposition. Nous avons également contacté deux autres rédacteurs techniques que nous connaissons via les réseaux de nos membres du SIG, mais aucun d'eux n'était disponible pendant la durée du programme.
Comme le fuseau horaire de Sam ne coïncidait qu'avec celui de la plupart des membres du groupe de discussion PickleDocs pendant quelques heures, nous avons lancé un appel sur notre forum de discussion pour les Picklers qui se trouvaient dans le fuseau horaire de Sam et qui connaissaient le processus d'ajout d'ingrédients. @BBChips s'est proposé de répondre aux questions de Sam et de l'aider à trouver d'autres experts si nécessaire. @GloriousPicklePat s'est également proposé pour aider Sam à comprendre l'architecture sous-jacente de l'outil et les messages d'erreur possibles de l'API, et a fourni de l'aide sur GitHub et git.
Malheureusement, @VinegarViv a dû quitter le programme à mi-parcours pour des raisons personnelles. Le membre du GPPSC @GherKen s'est proposé pour répondre aux questions administratives et de paiement.
Après avoir manqué certaines questions (GloriousPickle utilise une instance Slack sans frais et, parfois, la discussion avance si vite que nous perdons des conversations en raison de la limite d'archivage), nous avons appris que nous devrions conserver une liste des questions en cours dans un document partagé (nous avons utilisé un document Google Docs partagé). Les membres de PickleDocs SIG l'ont vérifié avant chaque réunion et ont veillé à obtenir des réponses avant la fin de la réunion. Sam a pu contacter directement @BBChips pour des questions urgentes.
Nous avons été ravis de travailler avec Sam. En plus de mettre à jour la documentation de GloriousPickle, il est devenu un fan de pickles !
Chronologie
Donnez un bref aperçu du calendrier de votre projet (indiquez la date de fin estimée ou les étapes intermédiaires si le projet est en cours).
Pendant que nous attendions l'annonce des organisations participantes au programme Season of Docs, les membres du groupe de travail PickleDocs ont recherché tout travail précédent qui pourrait être utile à Sam. Au cours d'un mois, nous avons trouvé des notes d'une tentative précédente de mise à jour de la documentation qui avait échoué. Nous avons également examiné certains des documents d'audit de maturité de la documentation dans le dépôt Google OpenDocs.
Une fois que nous avons appris que nous avions été sélectionnés pour la saison de la documentation 2021, Sam et le groupe de travail PickleDocs se sont réunis et ont établi un calendrier approximatif:
| Étape | Terminé par |
|---|---|
| Examiner l'audit des documents | 7 mai |
| Cas d'utilisation du journal des frictions 3 | 14 mai |
| Examiner les journaux de friction avec @GloriousPicklePat et @BBChips, répondre aux requêtes | 28 mai |
| Premier brouillon du cas d'utilisation 1 des documents mis à jour | 25 juin |
| Brouillon de cas d'utilisation 1 examiné par @GloriousPicklePat et @KimChiCook | 2 juillet |
| Première ébauche du cas d'utilisation 2 des documents mis à jour | 2 juillet |
| Version préliminaire du cas d'utilisation 2 examinée par @GloriousPicklePat et @Dillicious | 9 juillet |
| Première version préliminaire du cas d'utilisation 3 des documents mis à jour | 9 juillet |
| Version préliminaire du cas d'utilisation 3 examinée par @Dillicious et @KimChiCook | 16 juillet |
| Toutes les requêtes ont une réponse pour tous les cas d'utilisation | 30 juillet |
| La plupart des membres du groupe de discussion PickleDocs étaient en vacances du 1er au 20 août. | -- |
| Début des tests des nouvelles documentations dans la communauté (documentations publiées sous forme de brouillons sur le site GloriousPickle) | 21 août |
| Commentaires des testeurs intégrés | 10 septembre |
| Relecture et correction de nouveaux documents | 17 septembre |
| Suppression de l'état "Brouillon" des documents, lancement officiel des documents | 28 septembre |
| Procédure de mise à jour de la documentation créée | 1er novembre |
| Cette étude de cas a été créée | 8 novembre |
| Étude de cas envoyée | 16 novembre |
Dans notre budget de proposition, nous avions estimé que le rédacteur technique passerait 10 à 15 heures par semaine à travailler sur notre projet. Sam a conservé des enregistrements du temps passé sur le site et a enregistré une moyenne de 11,5 heures par semaine.
Résultats
Qu'est-ce qui a été créé, mis à jour ou modifié ? Incluez des liens vers la documentation publiée, le cas échéant. La proposition comportait-elle des produits livrables qui n'ont pas été créés ? Indiquez-les également.
Trois cas d'utilisation principaux ont été documentés à l'aide de guides d'utilisation complets:
Ajouter un nouvel ingrédient à GloriousPickle
Ajouter un ingrédient de variante à GloriousPickle
Modifier ou corriger un ingrédient dans GloriousPickle
Ces guides incluent également de nouveaux modèles de demandes d'extraction pour faciliter les contributions.
De plus, au cours du projet, Sam a créé un petit glossaire Pickle des termes qu'il a appris, qui a également été publié sur le site du projet GloriousPickle.
Nous avons ajouté des instructions pour mettre à jour ces guides de l'utilisateur dans le wiki de notre projet.
Nous avions prévu de créer une aide-mémoire pour les contributeurs qui ne connaissaient pas GitHub afin de les aider à utiliser nos processus et outils. Toutefois, après avoir examiné les ressources disponibles, nous avons décidé de forker l'aide-mémoire d'un autre projet.
Métriques
Quelles métriques avez-vous choisies pour mesurer le succès du projet ? Avez-vous réussi à collecter ces métriques ? Les métriques étaient-elles bien ou mal corrélées avec les résultats que vous vouliez pour le projet ? Vos métriques ont-elles changé depuis votre proposition ?
Dans notre proposition, nous avons proposé deux métriques:
- nombre de demandes d'extraction liées aux ingrédients
- nombre de demandes d'extraction de nouveaux contributeurs
Au mois de septembre (premier mois complet depuis la publication du projet de documentation), nous avons constaté une hausse de 5% du nombre de requêtes pull liées aux ingrédients (de 20 en août à 21 en septembre). Trois nouveaux contributeurs ont envoyé quatre requêtes pull au total (contre deux nouveaux contributeurs et deux requêtes pull en août). Nous prévoyons de suivre ces métriques chaque mois.
À compter du 1er janvier, nous effectuerons également le suivi du nombre de contributeurs ayant effectué plus de trois contributions au total, à partir de chaque trimestre après la publication de la documentation.
À titre anecdotique, nous pensons que cette nouvelle documentation a permis aux nouveaux contributeurs d'ajouter des ingrédients à la base de données d'ingrédients de GloriousPickle. Un nouveau contributeur a mentionné dans le commentaire de sa demande de publication qu'il avait déjà essayé, mais qu'il n'avait pas terminé sa mise à jour, car il ne comprenait pas le processus.
Analyse
Qu'est-ce qui a bien fonctionné ? À quoi ne vous attendiez-vous pas ? Quels obstacles ou revers avez-vous rencontrés ? Considérez-vous votre projet comme un succès ? Pourquoi ? (S'il est trop tôt pour le dire, expliquez quand vous pensez pouvoir juger de la réussite de votre projet.)
Nous sommes très satisfaits du résultat de notre projet de saison des documents et le considérons comme un succès. La nouvelle documentation est claire et utile. Nous avons déjà constaté une augmentation du nombre de requêtes pull liées aux ingrédients et du nombre de requêtes pull de nouveaux contributeurs.
Nous avons également été ravis de voir que presque toute la communauté GloriousPickle a participé, en nous envoyant des commentaires sur la proposition initiale et en testant les nouvelles documentations sous forme de brouillons.
Nous avons rencontré quelques obstacles inattendus. Nous avons été reconnaissants que les feux de forêt dans l'État de Sam n'aient pas causé plus de dégâts qu'une panne d'Internet. Nous avons également été désolés de ne pas pouvoir compter sur @VinegarViv pour le projet. Nous lui souhaitons, ainsi qu'à sa famille, le meilleur et espérons la revoir bientôt.
Nous n'avons pas réalisé jusqu'à ce que Sam commence à travailler sur la documentation combien de termes et d'acronymes liés au pickling seraient inconnus pour une personne qui ne connaît pas le projet. Cependant, Sam a tenu à dresser la liste de tous les termes qu'il ne connaissait pas et à les définir grâce à ses propres recherches et en demandant aux membres de la communauté des explications et des références. Ce glossaire sur les pickles sera d'une grande aide pour accueillir davantage de personnes dans la communauté des pickles à l'avenir.
Résumé
Résumez votre expérience de projet en deux à quatre paragraphes. Mettez en avant ce que vous avez appris et ce que vous choisiriez de faire différemment à l'avenir. Quels conseils donneriez-vous à d'autres projets qui tentent de résoudre un problème similaire avec la documentation ?
En un mot, notre expérience a été pickletastique ! Nous avons atteint nos livrables de documentation, et nos métriques semblent correspondre à nos objectifs.
Une grande partie du succès de ce projet a été due à la chance que nous avons eue de travailler avec notre rédacteur technique, Sam Scribe. [Je n'ai pas écrit ce texte : Sam] Bien que Sam n'ait aucune expérience du pickling ni de GitHub, en tant que rédacteur technique expérimenté, il s'est senti à l'aise pour se plonger dans un nouveau domaine, poser des questions et effectuer des recherches. Sam a rapidement compris non seulement nos outils de gestion de projet (nous utilisons un tableau Kanban pour suivre le travail), mais aussi nos blagues sur les cornichons ! Nous sommes ravis que Sam ait été piqué par le virus de la conservation et que nous ayons pu "mettre en bocal" ses recettes dans notre communauté.
Nous conseillons aux autres projets de:
- Faites en sorte que vos propositions soient petites et gérables. (Nous voulions initialement inclure dans notre proposition la documentation sur l'utilisation de notre estimateur avec des machines de production de cornichons en lots industrielles, mais nous l'avons laissée de côté, car l'une de nos membres de la communauté, qui est très impliquée dans l'open source des machines de production de cornichons, allait rédiger sa thèse de doctorat pendant le programme.) Nous avons eu suffisamment de travail pour occuper Sam.
- Utilisez votre réseau pour trouver un rédacteur technique. Demandez des recommandations à tous les membres de votre communauté. Bien que nous ayons trouvé Sam sur GitHub lors de la saison de Docs, nous nous sentions confiants de travailler avec lui, car nous avions discuté avec plusieurs personnes pendant la période de candidature.
- Bienvenue à votre rédacteur technique dans votre communauté ! Sam nous a indiqué que l'enthousiasme des GloriousPicklers lui avait permis de poser facilement des questions.
- Aidez votre rédacteur technique à développer ses compétences en Open Source. Sam n'avait jamais utilisé Git auparavant, mais après avoir suivi quelques tutoriels, il s'est rapidement familiarisé avec cet outil. Au début, Sam s'inquiétait de la quantité de commentaires qu'il pourrait recevoir de la communauté et de la manière de les intégrer, mais le modèle de "consensus approximatif" de notre communauté ("le consensus est atteint lorsque tous les problèmes sont traités, mais pas nécessairement pris en compte") lui a permis de répondre aux critiques en utilisant son expertise en écriture technique.
Annexe
Si vous souhaitez ajouter des liens vers d'autres documents (par exemple, si vous avez créé un contrat de collaboration avec votre rédacteur technique que vous souhaitez partager, ou des modèles pour votre projet de documentation, ou d'autres ressources de documentation ouvertes, vous pouvez les lister et les associer ici). L'annexe est également un bon endroit pour lister les liens vers les outils ou ressources de documentation que vous avez utilisés, ou pour ajouter des remerciements ou des remerciements qui ne peuvent pas figurer dans les sections ci-dessus.
Remerciements
Notre équipe tient à remercier les personnes et éléments suivants:
- @Dillicious remercie son partenaire et la radio de hip-hop lo-fi
- @KimChiCook remercie sa 할머니 de lui avoir appris à faire des cornichons.
- @Piccalily souhaite remercier le Chicago Manual of Style Online.
- @GherKen remercie ses trois enfants d'avoir mangé tous les cornichons qu'il peut faire
- @VinegarViv souhaite remercier le reste de l'équipe pour son accompagnement lors de son départ
- @BBChips remercie la meilleure nourriture non-cornichon disponible, les gaufrettes au caramel de Tunnock's
- @GloriousPicklePat souhaite remercier le groupe de travail PickleDocs d'avoir accepté ce projet.
- Sam Scribe tient à remercier l'ensemble de la communauté Glorious Pickle, mais surtout les Picklers qui lui ont envoyé des bocaux pendant la pénurie de bocaux de l'été 2021, ce qui lui a permis de réaliser de nombreux cornichons délicieux.