Phase actuelle:
Résultats annoncés. Consultez la chronologie.
Utilisez cet exemple pour vous aider à créer votre propre rapport d'étude de cas.
PicklePlus: documentation du GloriousPickle Contribution Tool
Organisation ou projet: Glorious Pickle lien vers le site principal de votre organisation ou projet ici
Description de l'organisation: GloriousPickle (version 1.2.3 actuelle, disponible pour la première fois en 2009) est une bibliothèque sous licence du MIT qui permet de calculer facilement le rapport idéal de sel, de sucre, de vinaigre et d'épices pour chaque légume cornichable. Des quantités allant d'un bébé concombre solitaire à des conteneurs de radis.
Auteurs: facultatif: lister les auteurs de l'étude de cas ; indiquer les noms d'utilisateur si nécessaire
Énoncé de problème/Résumé de la proposition
Quel problème cherchiez-vous à résoudre à l'aide de nouvelles documents ou d'une documentation améliorée ? Si possible, ajoutez un lien vers la page de 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 chronophage et compliqué, et l'outil ne dispose pas d'une bonne documentation. De nombreux contributeurs potentiels n'ont aucune expérience de l'utilisation de Git ni des demandes d'extraction. Cela signifie que GloriousPickle présente de graves lacunes dans nos données sur les ingrédients et rend notre outil moins utile. En améliorant la documentation sur l'ajout de nouveaux ingrédients, nous espérons encourager les nouveaux contributeurs et plus de vinaigre !
Description du projet
Créer la proposition
Comment avez-vous élaboré votre proposition Google Season of Docs ? Quel processus votre organisation a-t-elle utilisé pour prendre une idée ? Comment avez-vous sollicité et intégré des commentaires ?
Le GloriousPickle PickleDocs SIG a entendu parler du programme Google Season of Docs via un tweet du bureau des programmes Open Source de Google. Le SIG a discuté du programme lors de sa réunion bihebdomadaire et a accepté de rédiger une proposition. Deux membres du SIG (@KimChiCook et @Dillicious) se sont portés volontaires pour travailler sur le projet de proposition pour examen lors de la prochaine réunion.
Une fois que le SIG PickleDocs a accepté le projet de proposition, un e-mail a été envoyé à l'ensemble du projet pour demander des commentaires. Quatorze membres de la communauté ont donné leur avis, y compris @GloriousPicklePat, le responsable de l'API d'ajout d'ingrédients. @GloriousPicklePat s'est porté volontaire pour devenir une ressource pendant le programme.
Après avoir discuté et intégré les commentaires reçus, la proposition a été envoyée au comité directeur du projet GloriousPickle pour un vote. Les cinq membres de la GPPSC ont voté +1 pour l'envoi de la proposition et de la candidature, et @VinegarViv a accepté de participer à la création du compte Open Collective requis pour participer au programme et superviser les paiements.
Budget
Incluez une courte section sur votre budget. Comment avez-vous estimé le travail ? Y a-t-il eu des dépenses imprévues ? Avez-vous finalement dépensé moins que le montant de la subvention ? Avez-vous alloué les fonds correctement ou certains articles étaient-ils plus/moins/utilisés en budget ? Aviez-vous pu utiliser d'autres fonds en dehors de Google Season of Docs ?
Deux membres du GloriousPickle PickleDocs SIG ont travaillé comme rédacteurs techniques (un en Europe et un en Argentine). Ils nous ont aidés à estimer le travail et à trouver des budgets de projet similaires, en comparant le projet de proposition de travail qu'ils avaient effectué auparavant. Il nous restait également 1 000 US$de subventions de sponsoring illimitées de notre convention PicklePals de 2019 que nous avons allouées au projet.
Une dépense imprévue a aidé notre rédacteur technique à louer un point d'accès Wi-Fi, car il se trouvait dans une zone touchée par des incendies et la perte d'accès à Internet à son domicile. Nous avons également fini par envoyer moins de t-shirts aux participants que nous ne l’avions prévu, ce qui compense cela.
De plus, nous avons décidé de récompenser @Piccalily, une contributeur de GloriousPickle, qui était autrefois rédactrice en chef professionnelle dans sa vie de non-pickle, pour l'aider à corriger et à corriger la documentation créée par la rédactrice 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 ? Est-ce que quelqu'un a abandonné ? Qu'avez-vous appris sur le recrutement, la communication et la gestion de projet ?
L'équipe de base qui travaillait sur ce projet était:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (aide administrateur, GPPSC)
- @BBChips, @GloriousPicklePat (experts du domaine)
- Sam Scribe (rédacteur technique)
Nous avons trouvé Sam Scribe via la liste GitHub de Google Season of Docs. Nous avons trouvé 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 bihebdomadaire de PickleDocs SIG et il a pris la parole sur le projet avec nous, en nous faisant plusieurs suggestions très précieuses que nous avons intégrées dans la proposition. Nous avons également contacté deux autres rédacteurs techniques connus via les réseaux de nos membres du SIG, mais aucun d'entre eux n'était disponible au cours de la période du programme.
Comme le fuseau horaire de Sam ne chevauche que quelques heures avec celui de la plupart des membres du SIG PickleDocs, nous avons lancé un appel dans notre forum de discussion pour Picklers, qui était dans le fuseau horaire de Sam et connaissait le processus d'ajout d'ingrédients. @BBChips s'est porté volontaire pour répondre aux questions de Sam et l'aider à trouver d'autres experts si nécessaire. @GloriousPicklePat s'est également porté volontaire pour aider Sam à comprendre l'architecture sous-jacente de l'outil et les éventuels messages d'erreur de l'API, et lui a fourni une aide sur GitHub et Git.
Malheureusement, à mi-chemin du programme, @VinegarViv a dû prendre du recul sur le projet pour des raisons personnelles. @GherKen, membre de la GPPSC, s'est occupé de lui pour répondre aux questions administratives et de paiement.
Après quelques questions manquées (GloriousPickle utilise une instance Slack sans frais et, parfois, la discussion se déroule si rapidement que la limite glissante d'archives perd la conversation), nous avons appris que nous devions conserver une liste des questions en cours dans un document partagé (nous avons utilisé un document Google partagé). Les membres de PickleDocs l'ont vérifié avant chaque réunion et ont veillé à obtenir les réponses avant la fin de la réunion. Sam a pu contacter directement @BBChips pour des questions urgentes.
Nous étions très heureux de travailler avec Sam et Sam, en plus de mettre à jour la documentation de GloriousPickle, qui sont devenus des amateurs de pickle !
Chronologie
Présentez brièvement le calendrier de votre projet (indiquez la date de fin estimée ou les étapes intermédiaires si le projet est en cours).
En attendant que le programme Google Season of Docs annonce les organisations participantes, les membres de PickleDocs du SIG ont effectué des recherches sur tous les travaux antérieurs que nous pensions utiles pour Sam. En l'espace d'un mois, nous avons trouvé quelques notes issues d'une initiative antérieure de mise à jour de la documentation qui avait été bloquée. Nous avons également travaillé sur certaines parties des documents d'audit de maturité de la documentation disponibles dans le dépôt Google Opendocs.
Lorsque nous avons eu la bonne nouvelle d'avoir été sélectionnés pour Google Season of Docs, Sam et le PickleDocs SIG ont établi un calendrier approximatif:
| Étape | Terminée par |
|---|---|
| Examiner l'audit des documents | 7 mai |
| Cas d'utilisation du journal de friction 3 | 14 mai |
| Consulter les journaux de friction avec @GloriousPicklePat et @BBChips, répondre aux requêtes | 28 mai |
| Première version préliminaire du cas d'utilisation de documents mis à jour 1 | 25 juin |
| Brouillon de cas d'utilisation 1 examiné par @GloriousPicklePat et @KimChiCook | 2 juillet |
| Première ébauche du cas d'utilisation 2 de documents mis à jour | 2 juillet |
| Brouillon de cas d'utilisation 2 examiné par @GloriousPicklePat et @Dillicious | 9 juillet |
| Première ébauche du cas d'utilisation de documents 3 mis à jour | 9 juillet |
| Brouillon du cas d'utilisation 3 examiné par @Dillicious et @KimChiCook | 16 juillet |
| Réponses à toutes les requêtes pour tous les cas d'utilisation | 30 juillet |
| La plupart des appareils PickleDocs SIG étaient en vacances du 1er au 20 août | -- |
| Commencer à tester de nouveaux documents dans la communauté (documents publiés en tant que brouillons sur le site GloriousPickle) | 21 août |
| Commentaires sur les tests intégrés | 10 septembre |
| Copie et relecture de nouveaux documents | 17 septembre |
| État du brouillon de Docs supprimé, lancement officiel des documents | 28 septembre |
| Processus de mise à jour de la documentation créée | 1er novembre |
| Cette étude de cas a créé | 8 novembre |
| Étude de cas envoyée | 16 novembre |
Dans le budget de notre proposition, nous avions estimé que le rédacteur technique passerait 10 à 15 heures par semaine à travailler sur notre projet. Sam a gardé des registres du temps passé et a atteint 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. Y avait-il des produits livrables dans la proposition 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 ingrédient au GloriousPickle
Ajouter une variante d'ingrédient au GloriousPickle
Modifier ou corriger un ingrédient du GloriousPickle
Ces guides comprenaient également de nouveaux modèles de demande 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 pratiques de l'utilisateur dans le wiki de notre projet.
Nous avions inclus la création d'un aide-mémoire pour les contributeurs qui débutent sur GitHub afin de les aider à utiliser nos processus et nos outils, mais après avoir examiné les ressources disponibles, nous avons pu dupliquer l'aide-mémoire d'un autre projet à la place.
Métriques
Quelles métriques avez-vous choisies pour mesurer la réussite du projet ? Avez-vous pu collecter ces métriques ? Les métriques correspondaient-elles bien ou mal aux résultats que vous souhaitiez pour le projet ? Vos métriques ont-elles changé depuis votre proposition ?
Dans notre proposition, nous proposions deux métriques:
- nombre de demandes d'extraction liées aux ingrédients
- nombre de demandes d'extraction de nouveaux contributeurs
Pour le mois de septembre (le premier mois complet depuis la publication du brouillon de la documentation), nous avons constaté une augmentation de 5% des demandes d'extraction liées aux ingrédients (de 20 en août au 21 septembre), et trois nouveaux contributeurs ont effectué quatre demandes d'extraction au total (contre deux nouveaux contributeurs qui ont effectué deux demandes d'extraction en août). Nous prévoyons de suivre ces métriques une fois par mois.
À compter du 1er janvier, nous suivrons également le nombre de contributeurs ayant effectué plus de trois contributions au total, dès la publication des documents.
Pour l'anecdote, nous pensons que cette nouvelle documentation a fait une différence en permettant aux nouveaux contributeurs d'ajouter des ingrédients à la base de données des ingrédients GloriousPickle : un nouveau contributeur a mentionné dans un commentaire de son communiqué de presse qu'il avait déjà essayé, mais n'avait pas terminé sa mise à jour parce qu'il ne comprenait pas le processus.
Analyse
Qu'est-ce qui s'est bien passé ? Qu'est-ce qui était inattendu ? Quels obstacles ou difficultés avez-vous rencontrés ? Pensez-vous que votre projet a réussi ? Pourquoi ? (S'il est trop tôt pour le dire, expliquez à quel moment vous pensez pouvoir évaluer le succès de votre projet.)
Nous sommes très satisfaits du résultat de notre projet "Google Season of Docs" et considérons qu'il a réussi. La nouvelle documentation est claire et utile. Nous avons déjà constaté une augmentation du nombre de demandes d'extraction liées aux ingrédients et du nombre de demandes d'extraction de nouveaux contributeurs.
Nous sommes également ravis de la participation de la quasi-totalité de la communauté GloriousPickle, en envoyant des commentaires sur la proposition initiale et en testant les nouveaux documents sous forme de brouillon.
Nous avons fait face à quelques obstacles inattendus. Nous étions reconnaissants que les incendies dans l'État de Sam n'aient pas causé plus de dégâts qu'une panne d'Internet ! Nous étions également désolés de ne plus avoir participé à ce projet avec @VinegarViv. Nous vous souhaitons le meilleur pour votre famille et nous espérons la revoir bientôt.
Une chose dont nous n'avons pas réalisé que Sam a commencé à travailler sur la documentation était le nombre de termes et d'acronymes liés au pickle qui seraient inconnus d'une personne entrant dans notre projet sans expérience dans le cornichon. Cependant, Sam a fait en sorte de tenir une liste de tous les termes inconnus et les a définis lors de ses propres recherches et en demandant aux membres de la communauté des explications et des références. Ce glossaire Pickle sera d'une aide précieuse pour accueillir davantage de personnes dans la communauté des pickles à l'avenir.
Résumé
En deux ou quatre paragraphes, résumez votre expérience du projet. Mettez en évidence ce que vous avez appris et ce que vous choisiriez de faire différemment à l'avenir. Quel conseil donneriez-vous à d'autres projets qui essaient de résoudre un problème similaire grâce à la documentation ?
En un mot, notre expérience a été un choix de pickletastic ! Nous avons atteint nos livrables de documentation et nos métriques semblent correspondre à nos objectifs.
Une partie importante du succès de ce projet a été la chance que nous ayons eu la chance de travailler avec notre rédacteur technique, Sam Scribe. [Je n'ai pas écrit ceci — Sam] Bien que Sam n'ait aucune expérience dans le vinaigre ni aucune expérience avec GitHub, en tant que rédacteur technique expérimenté, il se sentait à l'aise pour explorer un nouveau domaine, poser des questions et effectuer des recherches. Sam a rapidement trouvé non seulement nos outils de projet (nous utilisons un tableau Kanban pour suivre notre travail), mais aussi nos blagues au cornichon ! Nous sommes très heureux que Sam ait attrapé le virus du cornichon et que nous les ayons mis en bouteille dans notre communauté.
Nous conseillons aux autres projets de:
- Veillez à ce que vos propositions soient petites et gérables. (À l'origine, nous voulions inclure de la documentation sur l'utilisation de notre Estimator avec des machines industrielles de décapage par lot dans notre proposition, mais nous ne l'avons pas prise en compte, car l'un des membres de notre communauté très impliqués dans la production de machines de pickle Open Source allait rédiger sa thèse de doctorat au cours du programme.) Nous avons fini par avoir suffisamment de travail pour occuper Sam !
- Utilisez vos réseaux lorsque vous recherchez un rédacteur technique. Demandez à tous les membres de votre communauté des recommandations. Bien que nous ayons trouvé Sam sur GitHub, nous nous sommes sentis confiants, car nous en avons parlé à plusieurs personnes au cours du processus de candidature.
- Accueillez votre rédacteur technique dans votre communauté ! Sam nous a fait savoir que l'attitude enthousiaste des GloriousPicklers permettait de poser facilement des questions.
- Aidez votre rédacteur technique à acquérir des compétences Open Source. Sam n'avait jamais utilisé git auparavant, mais après avoir suivi quelques tutoriels, il s'est rapidement mis au service. Au début, Sam Smith s'inquiétait du nombre de commentaires qu'elle pouvait recevoir de la part de la communauté et de la manière de les intégrer, mais grâce à son modèle "de consensus approximatif" ("consensus est atteint lorsque tous les problèmes sont résolus, mais pas nécessairement pris en charge"), Sam Smith s'est efforcé de traiter les critiques en toute confiance grâce à son expertise en rédaction technique.
Annexe
Si vous souhaitez partager d'autres documents (par exemple, si vous avez créé un contrat de travail avec votre rédacteur technique que vous souhaitez partager, des modèles pour votre projet de documentation ou d'autres ressources documentaires ouvertes, vous pouvez les répertorier et les lier ici). L'annexe est également un bon endroit pour répertorier des liens vers les outils ou ressources de documentation que vous avez utilisés, ou un endroit pour remercier ou remercier qui pourrait ne pas correspondre aux sections ci-dessus.
Remerciements
Notre équipe tient à remercier les personnes et points suivants:
- @Dillicious aimerait remercier sa compagne ainsi que la radio de hip-hop low-fi.
- @KimChiCook souhaite remercier son 할머니 qui lui a appris comment faire des cornichons.
- @Piccalily souhaite remercier le Chicago Manual of Style Online
- @GherKen souhaite remercier ses trois enfants d'avoir mangé tous les pickles qu'il peut préparer
- @VinegarViv souhaite remercier le reste de l'équipe d'avoir veillé à son départ.
- @BBChips souhaite remercier le meilleur aliment sans cornichon disponible, les gaufres au caramel Tunnock's
- @GloriousPicklePat souhaite remercier le PickleDocs SIG pour sa participation à ce projet
- Sam Scribe aimerait remercier toute la communauté du GloriousPickle, mais en particulier les Picklers qui leur ont envoyé des bocaux lors de la pénurie de bocaux de l'été 2021, ce qui les a lancés sur la route des délicieuses pickles.