Fase actual:
Se anunciaron los resultados. Consulta el cronograma.
Usa este ejemplo para crear tu propio informe de caso de éxito.
PicklePlus: documenta la herramienta de contribución de Glorious Pickle
Organización o proyecto: Glorious Pickle vínculo al sitio principal de tu organización o proyecto aquí
Descripción de la organización: GloriousPickle (versión actual 1.2.3, primer lanzamiento en 2009) es una biblioteca con licencia de MIT para calcular fácilmente la proporción perfecta de sal, azúcar, vinagre y especias para cada vegetal encurtable posible, en cantidades que van desde un solo pepino bebé solitario hasta contenedores llenos de rábanos.
Autores: Opcional: enumera a los autores del caso de éxito. Si se solicita, usa nombres de usuario.
Planteamiento del problema o resumen de la propuesta
¿Qué problema intentabas resolver con la documentación nueva o mejorada? Si es posible, vincula a la página de propuestas en el sitio de tu proyecto.
Agregar ingredientes a la base de datos de ingredientes de la herramienta GloriousPickle es lento y complicado, y la herramienta no tiene una buena documentación. Muchos posibles colaboradores no tienen experiencia en el uso de git ni en la realización de solicitudes de extracción. Esto significa que GloriousPickle tiene graves brechas en nuestros datos de ingredientes y hace que nuestra herramienta sea menos útil. Con la mejora de la documentación para agregar ingredientes nuevos, esperamos alentar a nuevos colaboradores y a que se preparen más encurtidos.
Descripción del proyecto
Creando la propuesta
¿Cómo surgieron tu propuesta de la temporada de Documentos de Google? ¿Qué proceso usó tu organización para decidir una idea? ¿Cómo solicitaste e incorporaste los comentarios?
El SIG de PickleDocs de GloriousPickle se enteró del programa de la Temporada de Documentos de Google a través de un tweet de la Oficina de Programas de Código Abierto de Google. El SIG analizó el programa en su reunión quincenal y acordó crear una propuesta. Dos miembros del SIG (@KimChiCook y @Dillicious) se ofrecieron como voluntarios para trabajar en el borrador de la propuesta para su revisión en la próxima reunión.
Una vez que el SIG de PickleDocs acordó el borrador de la propuesta, se envió un correo electrónico al proyecto en general para solicitar sus comentarios. Catorce miembros de la comunidad ofrecieron comentarios, incluido @Glorious PicklePat, el encargado de mantener la API que agrega ingredientes. @GloriousPicklePat se ofreció como recurso durante el programa.
Después de analizar e incorporar los comentarios recibidos, la propuesta se envió al comité directivo del proyecto Glorious Pickle para una votación. Los cinco miembros de GPPSC votaron +1 para enviar la propuesta y la solicitud, y @VinegarViv aceptó ayudar a crear la cuenta de Open Collective necesaria para participar en el programa y supervisar los pagos.
Presupuesto
Incluye una breve sección en tu presupuesto. ¿Cómo estimaste el trabajo? ¿Hubo algún gasto inesperado? ¿Terminaste gastando menos que el importe de la subvención? ¿Asignaste los fondos correctamente o algunos de los elementos para los que asignaste un presupuesto fueron excesivos, insuficientes o innecesarios? ¿Tuviste otros fondos fuera de la Temporada de Documentos de Google que pudiste usar?
Dos miembros del SIG de PickleDocs de GloriousPickle trabajaron como redactores técnicos (uno en Europa y otro en Argentina). Nos ayudaron a estimar el trabajo y a encontrar presupuestos de proyectos similares, y compararon el trabajo de la propuesta preliminar que habían hecho antes. También teníamos USD 1,000 en patrocinios sin restricciones de nuestra convención de PicklePals de 2019 que asignamos al proyecto.
Un gasto imprevisto fue ayudar a nuestro escritor técnico a alquilar un hotspot de Wi-Fi, ya que se encontraba en un área afectada por incendios forestales y perdió el acceso a Internet en su casa. Además, enviamos a los participantes menos camisetas de las que planeamos, así que el resultado fue equilibrado.
Además, decidimos compensar a una colaboradora de GloriousPickle, @Piccalily (que alguna vez fue editora profesional de textos en su vida no dedicada a los pepinillos) para que ayude con la edición y la corrección de la documentación creada por el redactor técnico.
Participantes
¿Quién trabajó en este proyecto (usa nombres de usuario si los participantes lo solicitan)? ¿Cómo encontraste y contrataste a tu redactor técnico? ¿Cómo encontraste a otros voluntarios o participantes pagados? ¿Qué puestos tenían? ¿Alguien abandonó el programa? ¿Qué aprendiste sobre el reclutamiento, la comunicación y la administración de proyectos?
El equipo principal que trabajó en este proyecto fue el siguiente:
- @Dillicious, @KimChiCook (SIG de PickleDocs)
- @Piccalily (editor)
- @GherKen, @VinegarViv (ayuda para administradores, GPPSC)
- @BBChips, @GloriousPicklePat (expertos en la materia)
- Sam Scribe (redactor técnico)
Encontramos a Sam Scribe en la lista del repositorio de GitHub de la Temporada de documentos de Google. Pensamos que su experiencia (Sam había trabajado para una revista culinaria y también había escrito documentación para sitios web) se ajustaba bien a nuestro proyecto. Sam se unió a la llamada quincenal del SIG de PickleDocs y habló con nosotros sobre el proyecto, y nos hizo varias sugerencias muy valiosas que incorporamos a la propuesta. También nos comunicamos con otros dos escritores técnicos que conocemos a través de las redes de nuestros miembros de SIG, pero ninguno de ellos estaba disponible durante el período del programa.
Como la zona horaria de Sam solo se superpuso unas horas con la mayoría de los miembros de PickleDocs SIG, enviamos una llamada en nuestro foro de debate para los Picklers que estaban en la zona horaria de Sam y estaban familiarizados con el proceso de agregar ingredientes. @BBChips se ofreció como voluntario para responder preguntas a Sam y ayudarlo a encontrar otros expertos según sea necesario. @GloriousPicklePat también se ofreció para ayudar a Sam a comprender la arquitectura subyacente de la herramienta y los posibles mensajes de error de la API, y brindó ayuda con GitHub y git.
Lamentablemente, a mitad del programa, @VinegarViv tuvo que dejar el proyecto por motivos personales. @GherKen, miembro de GPPSC, se incrementó para responder preguntas administrativas y de pagos.
Después de algunas preguntas perdidas (GloriousPickle usa una instancia gratuita de Slack y, en ocasiones, el debate avanza tan rápido que perdemos conversaciones debido al límite de archivo continuo), aprendimos que debemos mantener una lista de preguntas en curso en un documento compartido (usamos un Documento de Google compartido). Los miembros del SIG de PickleDocs lo revisaban antes de cada reunión y se aseguraban de obtener respuestas antes de que finalizara. Sam pudo enviar un ping a @BBChips directamente para hacer preguntas urgentes.
Fue un placer trabajar con Sam, quien, además de actualizar la documentación de GloriousPickle, se convirtió en un ávido usuario de este servicio.
Cronograma
Proporciona una breve descripción general del cronograma de tu proyecto (indica la fecha de finalización estimada o los eventos intermedios si el proyecto está en curso).
Mientras esperábamos que la temporada de Documentos de Google anunciara las organizaciones participantes, los miembros de SIG de PickleDocs hicieron una búsqueda sobre cualquier trabajo anterior que pensábamos que sería útil para Sam. En el transcurso de un mes, encontramos algunas notas de un esfuerzo anterior para actualizar la documentación que se había estancado, y también trabajamos en partes de los materiales de auditoría de madurez de la documentación en el repositorio de opendocs de Google.
Una vez que recibimos la buena noticia de que nos seleccionaron para la Temporada de Documentos de Google, Sam y el SIG de PickleDocs se reunieron y elaboraron un cronograma aproximado:
| Etapa | Completado por |
|---|---|
| Revisar auditoría de documentos | 7 de mayo |
| Casos de uso del registro de fricción 3 | 14 de mayo |
| Revisa los registros de fricción con @GloriousPicklePat y @BBChips, y responde las consultas | 28 de mayo |
| Primer borrador del caso de uso de documentos actualizados 1 | 25 de junio |
| El borrador del caso de uso 1 fue revisado por @GloriousPicklePat y @KimChiCook | 2 de julio |
| Primer borrador del caso de uso de Documentos actualizados 2 | 2 de julio |
| El borrador del caso de uso 2 fue revisado por @GloriousPicklePat y @Dillicious | 9 de julio |
| Primer borrador del caso de uso de documentos actualizados 3 | 9 de julio |
| Borrador del caso de uso 3 revisado por @Dillicious y @KimChiCook | 16 de julio |
| Todas las consultas respondidas en todos los casos de uso | 30 de julio |
| La mayoría de PickleDocs SIG estuvo de vacaciones del 1 al 20 de agosto | -- |
| Comienza a probar los documentos nuevos en la comunidad (documentos publicados como borradores en el sitio de GloriousPickle) | 21 de agosto |
| Se incorporaron los comentarios de las pruebas | 10 de septiembre |
| Edición y revisión de documentos nuevos | 17 de septiembre |
| Se quitó el estado de borrador de los documentos y se lanzaron oficialmente | 28 de septiembre |
| Se creó el proceso para actualizar la documentación | 1 de noviembre |
| Este caso de éxito creó | 8 de noviembre |
| Se envió el caso de éxito | 16 de noviembre |
En el presupuesto de nuestra propuesta, estimamos que el redactor técnico dedicaría entre 10 y 15 horas por semana a trabajar en nuestro proyecto. Sam llevó un registro del tiempo dedicado y obtuvo un promedio de 11.5 horas por semana.
Resultados
¿Qué se creó, actualizó o cambió de alguna otra manera? Si está disponible, incluye vínculos a la documentación publicada. ¿Hubo entregables en la propuesta que no se crearon? Indícalos también.
Se documentaron tres casos de uso principales con guías de instrucciones completas para el usuario:
Cómo agregar un ingrediente nuevo a GloriousPickle
Cómo agregar un ingrediente de variante a GloriousPickle
Cómo actualizar o corregir un ingrediente en GloriousPickle
Estas guías también incluyeron nuevas plantillas de solicitud de extracción para facilitar las contribuciones.
Además, durante el proyecto, Sam creó un pequeño Glosario de términos de Pickle que aprendió, que también se publicó en el sitio del proyecto GloriousPickle.
Agregamos instrucciones para actualizar estas guías prácticas para el usuario a nuestro wiki del proyecto.
Incluimos la creación de una hoja de referencia para los colaboradores que son nuevos en GitHub para ayudarlos a usar nuestros procesos y herramientas, pero una vez que revisamos los recursos disponibles, pudimos bifurcar la hoja de referencia de otro proyecto.
Métricas
¿Qué métricas elegiste para medir el éxito del proyecto? ¿Pudiste recopilar esas métricas? ¿Las métricas se correlacionaron bien o mal con los resultados que deseabas para el proyecto? ¿Cambiaron tus métricas desde que enviaste la propuesta?
En nuestra propuesta, propusimos dos métricas:
- cantidad de solicitudes de extracción relacionadas con ingredientes
- cantidad de solicitudes de extracción de colaboradores nuevos
En septiembre (el primer mes completo desde la publicación del borrador de la documentación), observamos un aumento del 5% en las solicitudes de extracción relacionadas con los ingredientes (de 20 en agosto a 21 en septiembre) y tres colaboradores nuevos que realizaron cuatro solicitudes de extracción en total (en comparación con dos colaboradores nuevos que realizaron dos solicitudes de extracción en agosto). Planeamos hacer un seguimiento de estas métricas mensualmente.
A partir del 1 de enero, también haremos un seguimiento de la cantidad de colaboradores que hayan realizado más de tres contribuciones en total, trimestralmente después de que se publique la documentación.
De manera anecdótica, creemos que esta nueva documentación marcó la diferencia en la posibilidad de que nuevos colaboradores agreguen a la base de datos de ingredientes de Glorious Pickle; un nuevo colaborador mencionó en el comentario de su RR.PP. que habían probado antes, pero que no habían completado la actualización porque no comprendían el proceso.
Análisis
¿Qué salió bien?, ¿Qué fue inesperado? ¿A qué obstáculos o obstáculos te enfrentaste? ¿Consideras que tu proyecto tiene éxito? ¿Por qué? (Si es demasiado pronto para decirlo, explica cuándo esperas poder juzgar el éxito de tu proyecto).
Estamos muy contentos con el resultado de nuestro proyecto de la Temporada de Documentos de Google y lo consideramos un éxito. La nueva documentación es clara y útil, y ya notamos un aumento en la cantidad de solicitudes de extracción relacionadas con los ingredientes y en la cantidad de solicitudes de extracción de colaboradores nuevos.
También nos alegró que casi toda la comunidad de GloriousPickle participara, ya sea con comentarios sobre la propuesta original o con pruebas de los documentos nuevos en forma de borrador.
Nos enfrentamos a algunos obstáculos inesperados. Estamos agradecidos de que los incendios forestales en el estado de Sam no hayan causado más daños que una interrupción de Internet. Además, lamentamos que @VinegarViv haya dejado el proyecto. Le deseamos a ella y a su familia lo mejor y esperamos verla pronto.
Algo que no nos dimos cuenta hasta que Sam comenzó a trabajar en la documentación era cuántos términos y acrónimos relacionados con el pickle no eran familiares para alguien que llegaba a nuestro proyecto sin experiencia previa. Sin embargo, Sam se aseguró de mantener una lista de todos los términos desconocidos y los definió a través de su propia investigación y pidiéndoles explicaciones y referencias a los miembros de la comunidad. Este glosario de Pickle será de gran ayuda para recibir a más personas en la comunidad de pickle en el futuro.
Resumen
Resume tu experiencia en el proyecto en 2 o 4 párrafos. Destaca lo que aprendiste y lo que harías de forma diferente en el futuro. ¿Qué consejo les darías a otros proyectos que intentan resolver un problema similar con la documentación?
En una palabra, nuestra experiencia fue pickletastic. Logramos los entregables de nuestra documentación y nuestras métricas parecen estar en línea con nuestros objetivos.
Una gran parte del éxito de este proyecto fue la suerte que tuvimos de trabajar con nuestro escritor técnico, Sam Scribe. [No escribí esto: Samuel] Aunque Sam no tenía experiencia en la selección ni en el uso de GitHub, como escritor técnico experimentado, se sentían cómodos para adentrarse en una nueva área temática, hacer preguntas y realizar investigaciones. Sam aprendió rápidamente no solo nuestras herramientas de proyecto (usamos un tablero Kanban para hacer un seguimiento del trabajo), sino también nuestros chistes sobre pepinillos. Nos alegra que Sam haya detectado el error de conservación en vinagre y que lo hayamos “embotellado” en nuestra comunidad.
Recomendamos a otros proyectos que hagan lo siguiente:
- Mantén tus propuestas pequeñas y fáciles de manejar. (Originalmente, queríamos incluir documentación para usar nuestro estimador con maquinaria industrial de encurtido por lotes en nuestra propuesta y solo la dejamos de lado porque una de las miembros de nuestra comunidad, muy involucrada en la maquinaria de encurtido de código abierto, iba a escribir su tesis de doctorado durante el programa). Tuvimos más que suficiente trabajo para mantener a Sam ocupado.
- Aprovecha tus redes cuando busques a un escritor técnico. Pídeles recomendaciones a todos los miembros de tu comunidad. Aunque encontramos a Sam a través de GitHub de la Temporada de Documentos de Google, nos sentimos seguros de trabajar con él porque hablamos con varias personas durante el período de postulación.
- Dale la bienvenida a tu comunidad al escritor técnico. Sam nos contó que la actitud entusiasta de GloriousPicklers facilitó el proceso de hacer preguntas.
- Ayuda a tu redactor técnico a adquirir habilidades de código abierto. Sam nunca había usado git antes, pero después de repasar algunos instructivos, se puso al día rápidamente. Al principio, Sam se preocupó por la cantidad de comentarios que podría recibir de la comunidad y cómo incorporarlos, pero el modelo de “consenso aproximado” de nuestra comunidad (“se logra un consenso cuando se abordan todos los problemas, pero no necesariamente se resuelven”) le dio confianza para abordar las críticas con su experiencia en redacción técnica.
Apéndice
Si tienes otros materiales a los que te gustaría vincular (por ejemplo, si creaste un contrato para trabajar con tu escritor técnico que te gustaría compartir, plantillas para tu proyecto de documentación o algún otro recurso de documentación abierta, puedes enumerarlos y vincularlos aquí). El Apéndice también es un buen lugar para enumerar vínculos a las herramientas o los recursos de documentación que usaste, o para agregar agradecimientos o reconocimientos que no se ajusten a las secciones anteriores.
Agradecimientos
Nuestro equipo quiere reconocer a las siguientes personas y elementos:
- @Dillicious quiere agradecer a su pareja y a la radio de hip hop de baja fidelidad
- @KimChiCook quiere agradecer a su 할머니 por enseñarle a preparar encurtidos.
- @Piccalily agradece al Manual de estilo de Chicago en línea
- @GherKen quiere agradecer a sus tres hijos por comerse todos los pepinillos que puede hacer.
- @VinegarViv quiere agradecer al resto del equipo por adaptarse a su renuncia
- @BBChips quiere agradecer a la mejor comida sin encurtido disponible, las obleas de caramelo de Tunnock
- @GloriousPicklePat quiere agradecer al SIG de PickleDocs por aceptar este proyecto.
- Sam Scribe quiere agradecer a toda la comunidad de GloriousPickle, en especial a los Picklers que le enviaron frascos de conserva durante la escasez de frascos del verano de 2021, lo que le permitió preparar muchos pepinillos deliciosos.