Fase actual:
Se anunciaron los resultados. Consulta el cronograma.
Usa este ejemplo para crear tu propio informe de caso de éxito.
PicklePlus: documentación de la herramienta de contribución GloriousPickle
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 del MIT que permite calcular fácilmente la proporción perfecta de sal, azúcar, vinagre y especias para cada verdura en recolección posible en cantidades que van desde un único pepino bebé solitario hasta cargas de rábanos en contenedores.
Autores: Opcional: Mencione los autores del caso de éxito; use los nombres de usuario si así se lo solicitan.
Resumen del problema/propuesta
¿Qué problema intentabas resolver con documentación nueva o mejorada? Si es posible, incluye un vínculo a la página de la propuesta en el sitio de tu proyecto.
Agregar ingredientes a la base de datos de ingredientes de la herramienta GloriousPickle es complicado y lleva mucho tiempo, y la herramienta no tiene 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 grandes vacíos en nuestros datos de ingredientes y hace que nuestra herramienta sea menos útil. Mejoramos la documentación para agregar ingredientes nuevos y, así, motivaremos a los colaboradores y a sumar más ingredientes de la cocina.
Descripción del proyecto
Cómo crear la propuesta
¿Cómo surgió la propuesta de la temporada de Documentos de Google? ¿Qué proceso usó tu organización para tomar una decisión sobre una idea? ¿Cómo solicitaste e incorporaste comentarios?
El equipo de SIG GloriousPickle PickleDocs escuchó sobre el programa Google Season of Docs mediante un tweet de la oficina de programas de código abierto de Google. El SIG debatió sobre 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 equipo de SIG de PickleDocs acordó el borrador de la propuesta, se envió un correo electrónico al proyecto en general para solicitar comentarios. Catorce miembros de la comunidad ofrecieron sus comentarios, incluido @GloriousPicklePat, el encargado del mantenimiento de la API para agregar ingredientes. @GloriousPicklePat se ofreció como voluntario para ser un recurso durante el programa.
Después de analizar e incorporar los comentarios recibidos, la propuesta se envió al comité directivo del proyecto GloriousPickle para una votación. Los cinco miembros del GPPSC votaron +1 en el envío de 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
Incluya una sección breve en su presupuesto. ¿Cómo estimaste el trabajo? ¿Hubo algún gasto inesperado? ¿Terminó gastando menos que el premio del subsidio? ¿Asignaste fondos correctamente o tenías que asignar más, menos o innecesariamente algunos elementos? ¿Tienes otros fondos además de Google Season of Documentos que pudiste usar?
Dos miembros del SIG GloriousPickle PickleDocs trabajaron como escritores técnicos (uno en Europa y otro en Argentina). Nos ayudaron a estimar el trabajo y a encontrar presupuestos de proyectos similares, comparando el trabajo de borrador de propuesta que habían hecho antes. También nos quedaron USD 1,000 en dinero para patrocinio ilimitado de nuestra convención de PicklePals de 2019 que asignamos al proyecto.
Un gasto imprevisto estuvo ayudando a nuestro escritor técnico a alquilar un hotspot de Wi-Fi, ya que se encontraba en una zona afectada por incendios forestales y perdieron el acceso a Internet en su casa. También terminamos enviando menos camisetas a los participantes de las que habíamos planeado, por lo que se equilibró.
Además, decidimos compensar a una colaboradora de GloriousPickle, @Piccalily (que alguna vez fue editora profesional en su vida poco personal) para que nos ayudara con la edición y la revisión de la documentación creada por la escritora técnica.
Participantes
¿Quién trabajó en este proyecto (usa nombres de usuario si los participantes lo solicitaron)? ¿Cómo encontraste y contrataste a tu escritor técnico? ¿Cómo encontraste otros voluntarios o participantes pagados? ¿Qué roles cumplieron? ¿Alguien se retiró? ¿Qué aprendiste sobre la selección de personal, la comunicación y la gestión de proyectos?
El equipo central que trabajaba en este proyecto era el siguiente:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (editor)
- @GherKen, @VinegarViv (ayuda para administradores, GPPSC)
- @BBChips, @GloriousPicklePat (expertos en la materia)
- Sam Scribe (escritor 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 de cocina y escribiendo documentación para sitios web) coincidía bien con nuestro proyecto. Sam se unió a la llamada quincenal de SIG de PickleDocs y conversó sobre el proyecto con nosotros y presentó varias sugerencias muy valiosas que incorporamos en la propuesta. También nos comunicamos con otros dos escritores técnicos que conocíamos a través de las redes de nuestros miembros de SIG, pero ninguno estuvo disponible durante el período del programa.
Debido a que la zona horaria de Sam solo se superpuso unas pocas horas con la mayoría de los miembros del SIG de PickleDocs, enviamos una llamada en nuestro foro de discusión para los Picklers que estaban en la zona horaria de Sam y estaban familiarizados con el proceso para agregar ingredientes. @BBChips se ofreció como voluntario para responder preguntas en nombre de Sam y para ayudarlos a encontrar otros expertos cuando fuera necesario. @GloriousPicklePat también se ofreció como voluntario para ayudar a Sam a comprender la arquitectura subyacente de la herramienta y los posibles mensajes de error de la API, y proporcionó ayuda de GitHub y Git.
Lamentablemente, a mitad del programa @VinegarViv tuvo que alejarse del proyecto por razones personales. El miembro de GPPSC @GherKen se encargó de las preguntas administrativas y de pagos.
Después de algunas preguntas omitidas (GloriousPickle usa una instancia gratuita de Slack y, en ocasiones, la conversación avanza tan rápido que perdemos conversaciones debido al límite continuo de archivos), descubrimos que deberíamos mantener una lista de preguntas en ejecución en un documento compartido (usamos un Documento de Google compartido). Los miembros del SIG de PickleDocs lo revisaron antes de cada reunión y se aseguraron de obtener las respuestas antes de finalizar. Sam pudo hacer ping a @BBChips directamente para preguntas urgentes.
Estábamos muy contentos de trabajar con Sam y Sam, además de actualizar la documentación de GloriousPickle, se convirtió en un ávido pickle.
Cronograma
Proporciona una breve descripción general del cronograma de tu proyecto (si el proyecto está en curso, indica la fecha de finalización estimada o los hitos intermedios).
Mientras esperábamos que el programa Temporada de Documentos de Google anunciara a las organizaciones participantes, los miembros del SIG de PickleDocs buscaron cualquier trabajo anterior que creímos 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 parado. También trabajamos a través de partes de los materiales de documentación de auditoría de madurez en el repositorio de documentos abiertos de Google.
Cuando tuvimos la buena noticia de que fuimos seleccionados para la temporada de Documentos de Google, Sam y el SIG de PickleDocs se reunieron y establecieron un cronograma difícil:
| Etapa | Completado por |
|---|---|
| Revisar la auditoría de documentos | 7 de mayo |
| Casos de uso del Registro de fricción 3 | 14 de mayo |
| Revisa registros de fricción con @GloriousPicklePat y @BBChips, y responde consultas | 28 de mayo |
| Primer borrador del caso de uso 1 de documentos actualizados | 25 de junio |
| Borrador del caso de uso 1 revisado por @GloriousPicklePat y @KimChiCook | 2 de julio |
| Primer borrador del caso de uso 2 de documentos actualizados | 2 de julio |
| @GloriousPicklePat y @Dillicious revisaron el borrador del caso de uso 2 | 9 de julio |
| Primer borrador del caso de uso 3 de documentos actualizados | 9 de julio |
| Borrador del caso de uso 3 revisado por @Dillicious y @KimChiCook | 16 de julio |
| Respuestas a todas las consultas en todos los casos de uso | 30 de julio |
| La mayoría de los SIG de PickleDocs se realizaron de vacaciones entre el 1 y el 20 de agosto. | -- |
| Comenzar a probar documentos nuevos en la comunidad (documentos publicados como borradores en el sitio de GloriousPickle) | 21 de agosto |
| Se incorporaron los comentarios sobre las pruebas | 10 de septiembre |
| Edición y revisión de documentos nuevos | 17 de septiembre |
| Se eliminó el estado del borrador de los documentos y se lanzaron oficialmente los documentos | 28 de septiembre |
| Se creó un proceso para actualizar la documentación | 1 de noviembre |
| Este caso práctico creó | 8 de noviembre |
| Caso de éxito enviado | 16 de noviembre |
En el presupuesto de la propuesta, habíamos estimado que el escritor técnico pasaría entre 10 y 15 horas por semana trabajando en nuestro proyecto. Sam mantuvo registros del tiempo dedicado y promediaba 11.5 horas por semana.
Resultados
¿Qué se creó, actualizó o cambió de alguna manera? Incluye vínculos a la documentación publicada, si está disponible. ¿Hubo algún entregable en la propuesta que no se creó? Enuméralos también.
Se documentaron tres casos de uso principales con guías prácticas de usuario completas:
Cómo agregar un ingrediente nuevo a GloriousPickle
Cómo agregar un ingrediente de variante a GloriousPickle
Cómo actualizar o corregir un ingrediente de GloriousPickle
En estas guías, también se incluyeron plantillas nuevas de solicitudes de extracción para facilitar las contribuciones.
Además, durante el proyecto, Sam creó un pequeño glosario de Pickle de los términos que aprendió, que también se publicó en el sitio del proyecto GloriousPickle.
Agregamos instrucciones para actualizar estas guías prácticas del usuario a la wiki de nuestro proyecto.
Incluimos la creación de una hoja de referencia para los colaboradores nuevos de GitHub para ayudarlos a usar nuestros procesos y herramientas, pero una vez que vimos 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 querías para el proyecto? ¿Tus métricas cambiaron desde la propuesta?
En nuestra propuesta, propusimos dos métricas:
- la cantidad de solicitudes de extracción relacionadas con componentes
- cantidad de solicitudes de extracción de nuevos colaboradores
En el mes de septiembre (el primer mes completo desde la publicación del borrador de la documentación), observamos un aumento del 5% en las solicitudes de incorporación de cambios relacionadas con los ingredientes (del 20 al 21 en septiembre) y vimos tres colaboradores nuevos que realizaron un total de cuatro solicitudes de extracción (en comparación con dos colaboradores nuevos que hicieron dos solicitudes en agosto). Planeamos hacer un seguimiento de estas métricas mensualmente.
A partir del 1 de enero, también realizaremos un seguimiento del número de colaboradores que hayan hecho más de tres contribuciones en total, a partir de la publicación trimestral de la documentación.
Anecdóticamente, creemos que esta nueva documentación marcó una diferencia a la hora de permitir que nuevos colaboradores se agreguen a la base de datos de ingredientes de GloriousPickle. Un colaborador nuevo mencionado en el comentario de su comunicado de prensa que ya había probado antes, pero que no había completado la actualización porque no comprendía el proceso.
Análisis
¿Qué salió bien? ¿Qué fue inesperado? ¿Qué obstáculos o contratiempos te enfrentaste? ¿Consideras que tu proyecto fue exitoso? ¿Por qué sí? ¿Por qué no? (Si es demasiado pronto para saberlo, explica cuándo esperas poder juzgar el éxito de tu proyecto).
Estamos muy contentos con el resultado de nuestro proyecto de temporada de Documentos de Google y lo consideramos un éxito. La documentación nueva es clara y útil, y ya observamos un crecimiento en la cantidad de solicitudes de incorporación de ingredientes relacionadas con los ingredientes y de nuevos colaboradores.
También nos alegró que casi toda la comunidad de GloriousPickle participara mediante comentarios sobre la propuesta original y probando los nuevos documentos en forma de borrador.
Nos enfrentamos a algunos obstáculos inesperados: estamos agradecidos de que los incendios forestales en el estado de Sam no causaron más daño que una interrupción de Internet. Además, lamentamos perder a @VinegarViv del proyecto. Le deseamos a ella y a su familia lo mejor y esperamos volver a verla pronto.
Algo de lo que no nos habíamos dado cuenta hasta que Sam comenzó a trabajar en la documentación era cuántos términos y acrónimos relacionados con el pickle le resultarían desconocidos para alguien que entraba a nuestro proyecto sin experiencia previa. Sin embargo, Sam se propuso 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 dar la bienvenida a más personas a la comunidad de pickle en el futuro.
Resumen
En 2 o 4 párrafos, resume tu experiencia con el proyecto. Destaca lo que aprendiste y lo que elegirías hacer de manera diferente en el futuro. ¿Qué consejo darías a otros proyectos que intentan resolver un problema similar con la documentación?
En una palabra, nuestra experiencia fue selectiva. Logramos los entregables de nuestra documentación y las métricas parecen estar alineadas con nuestros objetivos.
Una gran parte del éxito de este proyecto fue la suerte de trabajar con nuestro escritor técnico, Sam Scribe. [No escribí esto—Sam] Aunque Sam no tenía experiencia en selección ni experiencia con GitHub, como escritor técnico experimentado, se sentían cómodos adentrándose en una nueva área temática, haciendo preguntas e investigando. 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 de pickle. Estamos muy contentos de que Sam haya capturado el error y de que lo embotellamos en nuestra comunidad.
A los demás proyectos les aconsejaría que hagan lo siguiente:
- Las propuestas son pequeñas y manejables. (Originalmente, queríamos incluir en nuestra propuesta documentación para usar nuestro estimador con maquinaria industrial de selección por lotes y solo la omitimos porque uno de los miembros de nuestra comunidad que estaba muy involucrado en la maquinaria de pickle de código abierto iba a escribir su tesis de doctorado durante el programa). Terminamos teniendo más que suficiente trabajo para mantener a Sam ocupado.
- Aprovecha tus redes cuando busques un escritor técnico. Pídeles recomendaciones a todos los miembros de tu comunidad. Si bien descubrimos a Sam en la temporada de Documentos de Google en GitHub, nos sentíamos seguros de trabajar con ellos porque habíamos hablado con varias personas durante el período de postulación.
- Dale la bienvenida a tu escritor técnico a tu comunidad. Sam nos contó que la actitud entusiasta de los GloriousPicklers facilitó la tarea de hacer preguntas.
- Ayuda a tu escritor técnico a adquirir habilidades de código abierto. Sam nunca había usado git, pero después de revisar algunos instructivos, se pusieron al día rápidamente. Al principio, Sam estaba preocupado por la cantidad de comentarios que podían recibir de la comunidad y cómo incorporarlos, pero el modelo de "consenso aproximado" de nuestra comunidad ("el consenso se logra cuando se abordan todos los problemas, pero no necesariamente se acomoda") le daba confianza para abordar las críticas con su experiencia en redacción técnica.
Apéndice
Si tienes otros materiales que te gustaría vincular (por ejemplo, si creaste un contrato para trabajar con tu redactor 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 incluir vínculos a las herramientas o recursos de documentación que usaste, o bien para agregar agradecimientos o agradecimientos que podrían no encajar en las secciones anteriores.
Reconocimientos
Nuestro equipo desea agradecer a las siguientes personas y comentarios:
- @Dillicious quiere agradecer a su pareja y también a la radio de hip hop de baja fidelidad
- @KimChiCook quiere agradecer a su 할머니 por enseñarle a preparar pepinillos.
- @Piccalily agradece al Manual de estilo en línea de Chicago
- @GherKen quiere agradecer a sus tres hijos por comer todos los pepinillos que puede preparar
- @VinegarViv quiere agradecer al resto del equipo por el apoyo a su despedida
- @BBChips quiere agradecer a la mejor comida disponible sin pepinillos: Caramel Wafers de Tunnocks
- @GloriousPicklePat quiere agradecer al equipo de SIG de PickleDocs por asumir este proyecto
- Sam Scribe quiere agradecer a toda la comunidad de GloriousPickle, pero especialmente a los Picklers que les enviaron frascos de conserva durante el verano de 2021, lo que los trajo para probar muchos pepinillos deliciosos.