Fase actual:
Desarrollo de la documentación. 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, primera versión 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 vegetal conservable en cantidades, que van desde un único pepino bebé solitario hasta cargas de rábanos en contenedores.
Autores: Opcional: Indica los autores del caso de éxito; usa nombres de usuario si así se lo solicita.
Planteamiento del problema/Resumen de la 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 cuenta con una buena documentación. Muchos futuros colaboradores no tienen experiencia en el uso de Git ni en la realización de solicitudes de extracción. Esto significa que GloriousPickle tiene serios vacíos en nuestros datos de ingredientes y hace que nuestra herramienta sea menos útil. Al mejorar la documentación para agregar nuevos ingredientes, esperamos animar a los nuevos colaboradores y a realizar más conservaciones.
Descripción del proyecto
Cómo crear la propuesta
¿Cómo elaboraste tu propuesta para 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 GloriousPickle PickleDocs SIG se enteró del programa Google Season of Docs mediante un tweet desde la Oficina de Programas de Código Abierto de Google. Los SIG analizaron el programa en su reunión quincenal y aceptaron crear una propuesta. Dos miembros de SIG (@KimChiCook y @Dillicious) se ofrecieron como voluntarios para trabajar en el borrador de la propuesta para que se lo revise 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 de 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 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 sección breve en el presupuesto. ¿Cómo estimaste el trabajo? ¿Hubo algún gasto inesperado? ¿Terminó gastando menos que el premio de la subvención? ¿Asignaste fondos correctamente o tenías que gastar más, menos o innecesariamente algunos elementos? ¿Tenías otros fondos fuera de Google Season of Docs 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 proyecto similares, comparando el trabajo de propuesta preliminar que habían hecho antes. También nos quedaron USD 1,000 en dinero para patrocinio ilimitado de nuestra convención PicklePals de 2019 que asignamos al proyecto.
Un gasto imprevisto ayudó 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 habíamos planeado, por lo que se equilibró.
Además, decidimos compensar a un colaborador de GloriousPickle, @Piccalily (que una vez fue editora profesional en su vida 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é puestos desempeñaban? ¿Alguien abandonó el sistema? ¿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 de texto)
- @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 culinaria 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 habló sobre el proyecto con nosotros, haciendo 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 de estos 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 pescadores que se encontraban en la zona horaria de Sam y estaban familiarizados con el proceso de agregar ingredientes. @BBChips se ofreció como voluntario para responder preguntas para Sam y ayudarlo a encontrar otros expertos según 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 resolver las cuestiones administrativas y de pago.
Después de responder algunas preguntas omitidas (GloriousPickle usa una instancia gratuita de Slack y, en ocasiones, la discusión se mueve tan rápido que perdemos conversaciones debido al límite continuo de archivos), aprendimos que debí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 la reunión. Sam pudo hacer ping a @BBChips directamente para las preguntas urgentes.
Estuvimos muy contentos de trabajar con Sam y Sam, además de actualizar la documentación de GloriousPickle, se convirtió en un ávido pepinillo.
Cronograma
Proporciona una breve descripción general del cronograma de tu proyecto (indica la fecha de finalización estimada o los hitos intermedios si el proyecto está en curso).
Mientras esperábamos que el programa Temporada de Documentos de Google anunciara las organizaciones participantes, los miembros de 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 por actualizar la documentación que se había estancado y también trabajamos a través de partes de los materiales de auditoría sobre la madurez de la documentación en el repositorio de Google opendocs.
Cuando tuvimos la buena noticia de que fuimos seleccionados para la temporada de Documentos de Google, Sam y el equipo de SIG de PickleDocs se reunieron y establecieron un cronograma:
| 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 los registros de fricción con @GloriousPicklePat y @BBChips, y responde consultas | 28 de mayo |
| Primer borrador de caso de uso 1 de documentos actualizados | 25 de junio |
| @GloriousPicklePat y @KimChiCook revisaron el borrador del caso de uso 1 | 2 de julio |
| Primer borrador de 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 de 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 encontraban 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 borrador de los documentos; los documentos se lanzaron oficialmente. | 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 dedicaría entre 10 y 15 horas por semana a trabajar en nuestro proyecto. Samuel mantuvo registros del tiempo dedicado y promediaba 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 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 términos que aprendieron, 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 del 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 evaluamos 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? ¿Cambiaron sus métricas desde la propuesta?
En nuestra propuesta, propusimos dos métricas:
- la cantidad de solicitudes de extracción relacionadas con los ingredientes
- la cantidad de solicitudes de extracción de colaboradores nuevos
Durante 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 extracción relacionadas con los ingredientes (del 20 de agosto al 21 de septiembre) y vimos tres colaboradores nuevos que realizaron cuatro solicitudes de extracción en total (en comparación con dos colaboradores nuevos que hicieron dos solicitudes de extracción en agosto). Planeamos realizar un seguimiento de estas métricas mensualmente.
A partir del 1 de enero, también haremos un seguimiento del número de colaboradores que hayan realizado más de tres contribuciones en general, a partir del trimestre posterior a la publicación de la documentación.
De forma anecdótica, creemos que esta nueva documentación marcó una diferencia para permitir que nuevos colaboradores agreguen contenido a la base de datos de ingredientes de GloriousPickle. Se menciona un nuevo colaborador mencionado en el comentario de su comunicado de prensa que ya había probado antes, pero que no había completado su actualización porque no entendía el proceso.
Análisis
¿Qué salió bien? ¿Qué fue algo inesperado? ¿Qué obstáculos o contratiempos te enfrentaste? ¿Consideras que tu proyecto es exitoso? ¿Por qué? (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 Google Docs y lo consideramos un éxito. La nueva documentación es clara y útil, y ya observamos un crecimiento en la cantidad de solicitudes de extracción relacionadas con los componentes y en la de los colaboradores nuevos.
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 hayan provocado más daño que una interrupción de Internet. Además, lamentamos que @VinegarViv se quede en el proyecto. Le deseamos a ella y a su familia lo mejor y esperamos volver a verla pronto.
Algo de lo 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 los pepinillos no eran conocidos para una persona que ingresaba a nuestro proyecto sin experiencia previa. Sin embargo, Sam se propuso mantener una lista de todos los términos desconocidos y los definió mediante su propia investigación y pidiendo a los miembros de la comunidad explicaciones y referencias. Este glosario de Pickle será de gran ayuda para que más personas se unan a la comunidad de pepinillos 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 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 en consonancia con los 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 pepinillos ni experiencia con GitHub, como escritor técnico experimentado, se sintió cómodo adentrando en una nueva área temática, haciendo preguntas e investigando. Sam adoptó rápidamente no solo nuestras herramientas de proyecto (usamos un tablero Kanban para hacer un seguimiento del trabajo), sino también nuestras bromas de pepinillos. Nos alegra que Sam haya atrapado el pepinillo y que lo embotellamos en nuestra comunidad.
Recomendamos a otros proyectos que hagan lo siguiente:
- Las propuestas deben ser cortas y fáciles de manejar. (En un principio, queríamos incluir en nuestra propuesta documentación para usar nuestro estimador con maquinaria de recolección industrial por lotes y solo la dejamos fuera porque uno de los miembros de nuestra comunidad que estaba profundamente involucrado en la maquinaria de conservas de código abierto iba a escribir su tesis para el doctorado durante el programa). Terminamos con mucho trabajo para mantener a Sam ocupado.
- Cuando busques a un escritor técnico, aprovecha tus redes. Pídeles recomendaciones a todos los miembros de tu comunidad. Si bien descubrimos a Sam en el GitHub de la temporada de Documentos de Google, nos sentíamos confiados al trabajar con ellos porque habíamos hablado con varias personas durante el período de postulación.
- Dale la bienvenida al escritor técnico a tu comunidad. Sam nos contó que la actitud entusiasta de los GloriousPicklers facilitó la formulación de preguntas.
- Ayuda al 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, a Sam le preocupaba la cantidad de comentarios que obtendría 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 aborda") le da confianza para abordar las críticas utilizando su experiencia en redacción técnica.
Apéndice
Si quieres vincular otros materiales (por ejemplo, si creaste un contrato para trabajar con el redactor técnico que te gustaría compartir, plantillas para tu proyecto de documentación o cualquier otro recurso de documentación abierto), puedes enumerarlos y vincularlos aquí. El Apéndice también es un buen lugar para enumerar los vínculos a las herramientas de documentación o los recursos que usaste, o un lugar para agregar agradecimientos o reconocimientos que quizás no encajen en las secciones anteriores.
Agradecimientos
Nuestro equipo quiere reconocer a las siguientes personas y comentarios:
- A @Dillicious le gustaría agradecer a su pareja y también a la radio de hip hop de baja fidelidad
- @KimChiCook desea agradecer a su 할머니 por enseñarle a preparar pepinillos.
- A @Piccalily le gustaría agradecer 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 la aceptación de su parte.
- @BBChips quiere agradecer a la mejor comida sin pepinillos disponibles: las obleas de caramelo de Tunnock
- @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 la escasez de frascos del verano de 2021, lo que los inició en el camino a muchos pepinillos deliciosos.