Fase actual:
La temporada 2021 del programa Documentos finalizó el 14 de diciembre de 2021. Consulta el cronograma.
Usa este ejemplo para crear tu propio informe de caso de éxito.
PicklePlus: Documentación de la herramienta de contribución de GloriousPickle
Organización o proyecto: Glorious Pickle vincula aquí al sitio principal de tu organización o proyecto
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 la herramienta GloriousPickle requiere mucho tiempo y es complicado, 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 carencias 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
Crea la propuesta
¿Cómo se te ocurrió tu propuesta de la Temporada de Documentos? ¿Qué proceso usó tu organización para decidirse por una idea? ¿Cómo solicitaste y utilizaste los comentarios?
El SIG de PickleDocs de GloriousPickle se enteró del programa de la Temporada de Documentos a través de un tweet de la Oficina de Programas de Código Abierto de Google. El SIG debatió el programa en su reunión quincenal y acordó crear una propuesta. Dos miembros del SIG (@KimChiCook y @Dillicious) se ofrecieron voluntariamente a 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 más amplio para solicitar comentarios. Catorce miembros de la comunidad ofrecieron comentarios, incluido @GloriousPicklePat, el encargado de mantener la API de adición de 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 del GPPSC votaron a favor de 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 sobre tu presupuesto. ¿Cómo estimaste el trabajo? ¿Hubo algún gasto inesperado? ¿Terminaste gastando menos que el importe de la subvención? ¿Tuviste otros fondos fuera de la Temporada de Documentos 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, comparando el trabajo de borrador de propuesta 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. También enviamos menos camisetas a los participantes de lo que planeamos, por lo que se equilibró.
Además, decidimos compensar a una colaboradora de Gloriouspickle, @Piccalily (que alguna vez se desempeñó como editor de fotos profesional durante su vida profesional) para ayudar con la edición y revisión de la documentación creada por la escritora técnica.
Participantes
¿Quiénes trabajaron 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 la selección de personal, la comunicación y la gestió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. 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 de SIG de PickleDocs y habló con nosotros sobre el proyecto, haciendo varias sugerencias muy valiosas que incorporamos en 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 superponía unas horas con la mayoría de los miembros del SIG de PickleDocs, enviamos un llamado en nuestro foro de debate para que los usuarios de Picklers que estuvieran en la zona horaria de Sam y estuvieran 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. El miembro del equipo de GPPSC @GherKen se ofreció para responder preguntas administrativas y de pago.
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 hacer ping directamente a @BBChips para preguntas urgentes.
Estuvimos muy contentos de trabajar con Sam y Sam, además de actualizar la documentación de Glorious Pickle, que se ha convertido en un átomo de conservadores.
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 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. A lo largo de un mes, encontramos algunas notas de un esfuerzo anterior para actualizar la documentación que se había detenido, 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 2021, Sam y el SIG de PickleDocs se reunieron y elaboraron un cronograma aproximado:
| Etapa | Completado por |
|---|---|
| Revisa la 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 |
| El borrador del caso de uso 3 fue 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 | -- |
| Comenzar a probar 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 se 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? Incluye vínculos a la documentación publicada si está disponible. ¿Hubo algún producto de la propuesta que no se haya creado? Enumérelos 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 incluían nuevas plantillas de solicitudes de extracción para facilitar las contribuciones.
Además, durante el proyecto, Sam creó un pequeño glosario con los términos que aprendió en Pickle, 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? ¿Tus métricas cambiaron desde que la propusiste?
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 forma anecdótica, creemos que esta nueva documentación marcó la diferencia para permitir que los colaboradores nuevos agreguen a la base de datos de ingredientes de GloriousPickle. Un colaborador nuevo mencionó en el comentario de su PR que lo había intentado antes, pero no había completado la actualización porque no entendía el proceso.
Análisis
¿Qué salió bien? ¿Qué fue inesperado? ¿Qué obstáculos o contratiempos tuviste? ¿Consideras que tu proyecto tiene éxito? ¿Por qué? (Si es demasiado pronto para saberlo, explica cuándo esperas poder juzgar el éxito de tu proyecto).
Estamos muy satisfechos con el resultado de nuestro proyecto de la temporada de documentos 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.
Tuvimos algunos obstáculos inesperados: estábamos 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 que @VinegarViv haya dejado el proyecto. Le deseamos a ella y a su familia lo mejor y esperamos verla pronto.
Una cosa de la que no nos dimos cuenta hasta que Sam comenzó a trabajar en la documentación fue la cantidad de términos y acrónimos relacionados con los pepinillos que no le serían familiares a alguien que se uniera a nuestro proyecto sin experiencia en el tema. 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 encurtidos será de gran ayuda para dar la bienvenida a más personas a la comunidad de encurtidos 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 entregar la documentación y nuestras métricas parecen estar alineadas 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, Sam] Aunque Sam no tenía experiencia en el encurtido ni con GitHub, como escritor técnico experimentado, se sintió cómodo adentrándose en un área temática nueva, haciendo preguntas y realizando 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.
Les aconsejamos a otros proyectos que hagan lo siguiente:
- Mantenga sus propuestas breves y manejables. (Al principio, queríamos incluir documentación para usar nuestro estimador con maquinaria industrial de procesamiento por lotes en nuestra propuesta, pero solo lo omitimos porque uno de los miembros de nuestra comunidad, muy involucrado en la maquinaria de pickle 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 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, 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 los Glorious Picklers hizo que fuera fácil hacer preguntas.
- Ayuda a tu redactor técnico a adquirir habilidades de código abierto. Sam nunca había usado git, pero después de ver algunos instructivos, se adaptó 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 que quieras 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 u otros recursos de documentación abiertos, 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 pepinillos
- @Piccalily quiere agradecer el Manual de estilo en línea de Chicago
- @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 baja
- @BBChips quiere agradecer a la mejor comida no encurtida disponible, los wafers de caramelo de Tunnock
- @Glorious PicklePat quiere agradecer a PickleDocs SIG por participar en 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.