Phase actuelle:
Développement de la documentation. Consultez le calendrier.
Utilisez cet exemple pour vous aider à créer votre propre rapport d'étude de cas.
PicklePlus: documenter le GloriousPickle Contribution Tool
Organisation ou projet: Glorious Pickle cliquez ici pour accéder au site principal de votre organisation ou de votre projet.
Description de l'organisation: GloriousPickle (version actuelle 1.2.3, première sortie en 2009) est une bibliothèque sous licence du MIT qui permet de calculer facilement le ratio parfait de sel, sucre, vinaigre et épices pour chaque légume à cornichons, dans des quantités allant d'un petit concombre solitaire à des conteneurs de radis.
Auteurs: facultatif: listez les auteurs de l'étude de cas ; utilisez des noms d'utilisateur si demandé
Énoncé du problème/Extrait de la proposition
Quel problème cherchiez-vous à résoudre avec de la nouvelle documentation ou de la 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 des 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 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 d'autres méthodes pour le vinaigre !
Description du projet
Création de la proposition
Comment avez-vous élaboré votre proposition pour 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 créer une proposition. Deux membres du SIG (@KimChiCook et @Dillicious) se sont portés volontaires pour travailler sur le projet de proposition qui sera examiné lors de la prochaine réunion.
Une fois que le SIG PickleDocs a accepté l'ébauche de la 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 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 contribuer à la création du compte Open Collective nécessaire à la participation au programme et à la supervision des paiements.
Budget
Incluez une courte partie de 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 votre budget était-il plus/moins/négatif pour certains éléments ? Disposez-vous d'autres fonds en dehors de Google Season of Docs que vous pouviez utiliser ?
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$d'argent de sponsoring sans restriction de notre convention PicklePals de 2019 que nous avons alloué au projet.
Une dépense imprévue a permis à notre rédacteur technique de louer un point d'accès Wi-Fi, car il se trouvait dans une zone touchée par des incendies et ayant perdu l'accès à Internet à son domicile. Nous avons également fini par envoyer moins de t-shirts aux participants que prévu, ce qui s'est avéré efficace.
De plus, nous avons décidé de rémunérer une contributeur de GloriousPickle, @Piccalily (qui était autrefois rédactrice professionnelle dans son quotidien) pour l'aider à 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 étaient leurs rôles ? 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 travaillant sur ce projet était:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (éditeur de texte)
- @GherKen, @VinegarViv (aide administrateur, GPPSC)
- @BBChips, @GloriousPicklePat (experts du domaine)
- Sam Scribe (rédacteur technique)
Nous avons trouvé Sam Scribe via la liste du dépôt GitHub de Google Season of Docs. Nous pensions que son expérience (Sam avait travaillé pour un magazine culinaire et écrivait de la documentation pour des sites Web) concordait bien avec notre projet. Sam a participé à l'appel bihebdomadaire de PickleDocs SIG et nous a présenté le projet. Il nous a fait part de 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 SIG, mais aucun d'entre eux n'était disponible pendant la durée du programme.
Étant donné que le fuseau horaire de Sam ne chevauche que celui de la plupart des membres du SIG PickleDocs, nous avons envoyé un appel dans notre forum de discussion à l'intention de Picklers qui se trouvait dans le fuseau horaire de Sam et qui connaissaient 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. Il a également 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 employé à traiter les 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 vite que nous perdons des conversations en raison de la limite glissante d'archivage), 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 du SIG de PickleDocs les ont vérifiés 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 étions très heureux de travailler avec Sam et Sam, en plus de mettre à jour la documentation GloriousPickle, sont devenus eux-mêmes un ardeur de pickler !
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 du SIG PickleDocs ont recherché tous les travaux antérieurs que nous pensions utiles à Sam. En un mois, nous avons trouvé certaines notes issues d'une initiative précédente visant à mettre à jour la documentation qui avait été bloquée. Nous avons également passé en revue certaines parties des documents d'audit de maturité de la documentation dans le dépôt Opendocs de Google.
Après avoir reçu la bonne nouvelle que nous avons été sélectionnés pour Google Season of Docs, Sam et le PickleDocs SIG se sont réunis et ont élaboré une ébauche de calendrier:
| Étape | Terminé avant le |
|---|---|
| Consulter l'audit des documents | 7 mai |
| Journal de friction 3 : cas d'utilisation | 14 mai |
| Examiner les journaux de friction avec @GloriousPicklePat et @BBChips, répondre aux requêtes | 28 mai |
| Première version préliminaire 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 version préliminaire du cas d'utilisation 2 des documents mis à jour | 2 juillet |
| Brouillon du cas d'utilisation 2 examiné par @GloriousPicklePat et @Dillicious | 9 juillet |
| Première version préliminaire du cas d'utilisation 3 des documents 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 sites 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, révision et relecture de nouveaux documents | 17 septembre |
| État du brouillon des documents 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 notre budget de 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 utilisait 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, accompagnés de guides d'utilisation complets:
Ajouter un nouvel ingrédient au GloriousPickle
Ajouter un ingrédient de variante au GloriousPickle
Modifier ou corriger un ingrédient du GloriousPickle
Ces guides comprenaient également de nouveaux modèles de demandes d'extraction pour faciliter les contributions.
En outre, 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 d'utilisation de l'utilisateur à notre wiki de projet.
Nous avions inclus la création d'un aide-mémoire pour les contributeurs nouveaux 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 vouliez 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 provenant 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 août au 21 septembre), et trois nouveaux contributeurs ont effectué quatre demandes d'extraction au total (par rapport à deux nouveaux contributeurs qui ont effectué deux demandes d'extraction en août). Nous prévoyons de suivre ces métriques tous les mois.
À compter du 1er janvier, nous suivrons également le nombre de contributeurs ayant apporté plus de trois contributions au total, dès la publication de la documentation.
Pour l'anecdote, nous pensons que cette nouvelle documentation a fait une différence en permettant aux nouveaux contributeurs d'ajouter des produits à la base de données des ingrédients GloriousPickle. Un nouveau contributeur a mentionné dans un commentaire de son RP qu'il avait déjà essayé, mais qu'il n'avait pas terminé sa mise à jour parce qu'il n'avait pas compris le processus.
Analyse
Qu'est-ce qui s'est bien passé ? Quels sont les résultats inattendus ? Quels obstacles ou difficultés avez-vous rencontrés ? Pensez-vous que votre projet est réussi ? Pourquoi ? (S'il est trop tôt pour le dire, expliquez à quel moment vous pensez pouvoir juger de la réussite 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, et 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 provenant de nouveaux contributeurs.
Nous avons également été ravis que la quasi-totalité de la communauté GloriousPickle y ait participé en nous envoyant des commentaires sur la proposition initiale et en testant les nouveaux documents sous forme de brouillon.
Nous avons été confrontés à 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 d'avoir perdu @VinegarViv du projet. Nous souhaitons le meilleur à sa famille et à elle, et nous espérons la revoir bientôt.
Une chose que nous n'avons pas réalisé avant que Sam Smith n'ait commencé à travailler sur la documentation était combien de termes et d'acronymes liés aux pickles ne seraient pas familiers pour quelqu'un entrant dans notre projet sans expérience du pickle. Cependant, Sam a tenu une liste de tous les termes inconnus et les a définis dans ses propres recherches et en demandant aux membres de la communauté des explications et des références. Ce glossaire Pickle sera d'une grande aide pour accueillir davantage de personnes dans la communauté des pickles à l'avenir.
Résumé
Résumez en deux ou quatre paragraphes votre expérience du projet. Mettez en avant 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 avec la documentation ?
En un mot, notre expérience a été décisive ! Nous avons atteint nos produits livrables de la documentation et nos métriques semblent être en phase avec 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 ne l'ai pas écrit — Sam] Bien que Sam n'ait aucune expérience en matière de vinaigre ou n'ait pas d'expérience avec GitHub, en tant que rédacteur technique expérimenté, il se sentait à l'aise pour explorer un nouveau sujet, poser des questions et faire des recherches. Sam s'est rapidement familiarisé avec nos outils de projet (nous utilisons un tableau kanban pour suivre notre travail), mais aussi nos blagues de pickle ! Nous sommes très heureux que Sam ait attrapé l'insecte et que nous les ayons mis en bouteille dans notre communauté.
Nous conseillons aux autres projets de:
- Veillez à ce que vos propositions soient de taille modeste et gérables. (Au départ, nous voulions inclure dans notre proposition la documentation sur l'utilisation de notre Estimator avec des machines industrielles de décapage par lot, mais nous ne l'avons pas fait, car l'un des membres de notre communauté très impliqués dans les machines à pickle Open Source allait rédiger sa thèse de doctorat pendant le programme.) Nous avons fini par avoir suffisamment de travail pour occuper Sam !
- Tirez parti de vos réseaux lorsque vous recherchez un rédacteur technique. Demandez des recommandations à tous les membres de votre communauté. Bien que nous ayons trouvé Sam sur GitHub grâce à Google Season of Docs, nous nous sommes sentis confiants de pouvoir travailler avec lui, car nous en avions parlé à plusieurs personnes pendant le processus d'inscription.
- Accueillez votre rédacteur technique dans votre communauté ! Sam a expliqué que l'enthousiasme suscité par les GloriousPicklers lui 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 à la page. Au début, Sam Smith s'inquiétait du nombre de commentaires qu'elle pouvait obtenir de la part de la communauté et de la manière de les intégrer, mais le modèle de "consensus approximatif" de la communauté ("consensus est obtenu lorsque tous les problèmes sont résolus, mais pas nécessairement pris en charge") l'a incitée à répondre aux critiques en utilisant son expertise en rédaction technique.
Annexe
Si vous souhaitez créer un lien vers d'autres documents (par exemple, si vous avez créé un contrat de travail avec votre rédacteur technique et que vous souhaitez le partager, des modèles pour votre projet de documentation ou d'autres ressources de documentation 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 pour exprimer des remerciements ou des remerciements qui pourraient ne pas correspondre aux sections ci-dessus.
Remerciements
Notre équipe tient à remercier les personnes et les points suivants:
- @Dillicious souhaite remercier sa compagne ainsi que la radio de hip-hop low-fi.
- @KimChiCook souhaite remercier son 할머니 qui lui a appris comment concocter des cornichons.
- @Piccalily souhaite remercier le Chicago Manual of Style Online.
- @GherKen aimerait 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 gaufrettes au caramel Tunnock's.
- @GloriousPicklePat souhaite remercier le SIG PickleDocs d'avoir pris en charge ce projet
- Sam Scribe souhaite remercier l'ensemble de la communauté Glorious Pickle, mais en particulier ceux qui leur ont envoyé des bocaux en conserve pendant la pénurie de bocaux de l'été 2021, qui les ont lancés en route pour déguster de délicieux pickles !