Season of Docs es un programa de sustentabilidad administrado por la Oficina de Programas de Código Abierto de Google. Los objetivos de Season of Docs son los siguientes:
- Brindar asistencia a proyectos de código abierto para resolver problemas con la documentación
- Ofrecer a los redactores técnicos oportunidades para adquirir experiencia en código abierto
- Aumentar el conocimiento sobre el código abierto, la documentación y la redacción técnica
- Recopilar y compartir información sobre métricas eficaces en la documentación de código abierto
En el sitio web del programa, encontrarás más información sobre Season of Docs.
Descripción general del programa 2022
Cómo funciona Season of Docs
En Season of Docs, las organizaciones presentan una solicitud enviando una propuesta de proyecto. La propuesta de proyecto incluye lo siguiente:
- Información sobre la organización
- Una descripción del problema que enfrenta el proyecto
- Cómo el proyecto usará la documentación para ayudar a resolver su problema
- Cómo el proyecto medirá la eficacia de su documentación (métricas)
- Un cronograma del trabajo
- Un presupuesto del proyecto
- Cualquier información adicional, como la experiencia de la organización en programas similares o cualquier otra cosa que ayude a los administradores de Season of Docs a comprender su proyecto y problema
Una vez que se aceptan en el programa, las organizaciones reclutan y contratan directamente a sus propios redactores técnicos. Season of Docs usa Open Collective para financiar a las organizaciones, y estas les pagan a los redactores técnicos a través de Open Collective. Los presupuestos y los pagos de los proyectos son transparentes. Los presupuestos se incluyen en las propuestas de proyectos de las organizaciones disponibles en el sitio de Season of Docs, y los pagos son visibles en la cuenta de Open Collective de Season of Docs.
Se considera que las organizaciones completaron el programa con éxito cuando envían su informe de estudio de caso. También se les pide a las organizaciones que completen evaluaciones mensuales durante el programa y tres encuestas de seguimiento trimestrales durante el año posterior a la finalización del programa.
Aspectos destacados de 2022
"Después de que se lanzó el nuevo documento, las visitas diarias a Casbin y Casdoor casi se duplicaron, y los porcentajes de rebote disminuyeron en aproximadamente un 30%". —Casbin
"Un resultado encantador de este proyecto fue ver cómo [nuestros redactores técnicos] asumían roles de liderazgo en nuestra comunidad. Ambos colaboradores ahora lideran reuniones de grupos de trabajo y de la comunidad, además de contribuir al diseño y mantenimiento de nuestros proyectos". —moja-global
"[GSoD] nos ayudó a reclutar a dos redactores técnicos talentosos, lo cual es muy difícil en una configuración normal. Ellos siguen siendo colaboradores activos de SO en OpenMined, y tuvimos una excelente experiencia laboral con ellos". —OpenMined
"Además, el nuevo manual es mucho más fácil para los principiantes en espectrometría de masas computacional. Para ilustrar este punto, la subvención de CZI también proporciona estipendios para personas históricamente desfavorecidas, y algunos beneficiarios usaron el nuevo manual de OpenMS para iniciar su período de prácticas de seis semanas y dieron opiniones positivas sobre el nuevo manual". —OpenMS
Datos de resumen de 2022
En 2022, el programa Season of Docs aceptó 31 proyectos de 67 solicitudes, y 30 proyectos completaron el programa con éxito. De las 31 organizaciones aceptadas, 17 eran solicitantes recurrentes.
Los 31 proyectos aceptados contrataron a 58 redactores técnicos. Más de 190 redactores técnicos indicaron su interés en participar en el programa agregando su información de contacto y vínculos a sus portafolios en el repositorio de GitHub de Season of Docs.
Para el programa 2022:
- El 100% de las organizaciones tuvo una experiencia positiva con el proceso de solicitud.
- El 100% de las organizaciones tuvo una experiencia positiva con la documentación o el contenido del sitio web del programa.
- El 93% de las organizaciones tuvo una experiencia positiva con el programa.
- El 90% de las organizaciones consideró que su proyecto de documentación fue exitoso.
Acerca de las organizaciones
Las organizaciones que participaron en Season of Docs 2022 representaron una amplia variedad de proyectos de código abierto. La cohorte de 2022 incluyó lo siguiente:
- Herramientas de desarrollo, como AsyncAPI y SpyderIDE
- Lenguajes y marcos de programación, como Julia, LFortran, R, y p5.js
- Proyectos científicos, como CERN-HSF y SymPy
- Aplicaciones para usuarios finales, como Mautic, Open Food Facts, Talawa y Ushahidi
- Proyectos de hardware y robótica, como ExpressLRS y Open-RMF
- Proyectos de datos, como GeomScale, GeomStats, OpenMined y Weaviate
- Proyectos de infraestructura y nube, como cert-manager, NimbleEdge y Cilium
No recopilamos metadatos sobre los proyectos (como la fecha de fundación, la distribución geográfica de los colaboradores, la cantidad de colaboradores o el tamaño de la base de usuarios).
Les pedimos a los proyectos que indicaran qué licencia de código abierto usaban.
Acerca de los proyectos de documentación
Problemas de documentación
Entre los principales problemas que las organizaciones esperaban resolver con la documentación en el programa 2022, se incluyen los siguientes:
Ten en cuenta que las organizaciones podían informar varios problemas de documentación. Para obtener más detalles, consulta la página de resultados de Season of Docs 2022, que incluye vínculos a las propuestas de proyectos originales y a los estudios de caso completos de cada organización.
Tipos de documentación creados
La documentación instructiva fue el tipo de documentación más mencionado en los casos de éxito de 2022.
Entre otros tipos de documentación mencionados en los estudios de caso, se incluyen los siguientes:
- Guía de inicio rápido
- Glosario
- Preguntas frecuentes
- KnowledgeBase
- Componentes
- Contenido de blog o redes sociales
- Guía para el mantenedor
Algunas de estas categorías son imprecisas, y un solo proyecto de documentación podría contener varios tipos o funciones de documentación.
Para obtener más detalles, consulta la página de resultados de Season of Docs 2022, que incluye vínculos a las propuestas de proyectos originales y a los estudios de caso completos de cada organización.
Presupuestos
La solicitud de presupuesto promedio fue de USD 11,679, y la mediana fue de USD 12,150. Cinco organizaciones solicitaron y recibieron la subvención más alta disponible (USD 15,000), y tres solicitaron la más baja (entre USD 5,000 y USD 7,000).
Las métricas
En sus estudios de caso, los proyectos describieron las métricas que usaban para evaluar el éxito de sus proyectos de documentación.
Las principales métricas propuestas fueron las siguientes:
Entre otras métricas propuestas, se incluyen las siguientes:
- Más solicitudes de extracción o contribuciones de documentación
- Más comentarios directos en las páginas de documentación
- Tiempo de permanencia en la página
- Problemas planteados (como proxy de uso)
- Participantes en foros
- Cantidad de socios, voluntarios o integraciones
- Porcentaje de rebote reducido
- Mayor conocimiento en la comunidad
Debido al breve período entre la finalización de los proyectos de redacción técnica y el envío de los estudios de caso, la mayoría de la cohorte de 2022 no había podido recopilar suficientes datos en el momento de enviar sus estudios de caso para determinar si se habían cumplido o no sus métricas iniciales.
A medida que recibamos respuestas a las encuestas de seguimiento en 2023, actualizaremos este informe para agregar información sobre qué proyectos alcanzaron sus métricas o las revisaron.
Para obtener más detalles, consulta la página de resultados de Season of Docs 2022, que incluye vínculos a las propuestas de proyectos originales y a los estudios de caso completos de cada organización.
Trabaja con redactores técnicos
En el programa Season of Docs, se espera que los proyectos recluten, entrevisten, contraten y paguen directamente a los redactores técnicos. Los redactores técnicos pueden agregarse al directorio que mantiene Season of Docs en nuestro repositorio de GitHub, pero el personal de Season of Docs no investiga ni recomienda redactores técnicos.
Prácticas recomendadas para contratar redactores técnicos para proyectos de código abierto
Se les pidió a los proyectos que compartieran sus prácticas recomendadas para reclutar, contratar y trabajar con redactores técnicos. Las principales recomendaciones fueron las siguientes:
Reclutamiento
- Entrevista a menos candidatos y usa una sesión de práctica en vivo, en lugar de solo revisar los CV.
- Valora las habilidades de comunicación oral y escrita por sobre el dominio del lenguaje o las herramientas de tu proyecto.
- Haz preguntas directas sobre cómo el redactor técnico adquirirá los conocimientos del dominio necesarios para trabajar con tu proyecto.
- Es más probable que alguien con entusiasmo por la misión de tu proyecto y que comparte los valores fundamentales de código abierto se mantenga motivado durante todo el proyecto.
- Acepta candidatos de todo el mundo, ya que la diversidad de puntos de vista y antecedentes ayudará a tu proyecto, pero ten en cuenta que tener redactores y mentores en demasiadas zonas horarias en conflicto puede requerir mucho esfuerzo adicional para mantener una buena comunicación.
Vacantes
- Usa un contrato que indique claramente las entregas, los cronogramas de pago y los compromisos de tiempo específicos.
- Si tu proyecto tiene muchas incógnitas, incluye un hito para el descubrimiento o la investigación independiente de la creación de documentación.
Coordinación y comunicación
- Mantén un registro de reuniones en el que se registren las decisiones para que sea más fácil para todos los que trabajan en el proyecto comprender el contexto y los próximos pasos.
- Sé claro sobre qué comunicación se espera y con qué frecuencia, ya sean llamadas semanales, correos electrónicos diarios o actualizaciones de estado en un canal de chat.
- Responde y proporciona comentarios claros que incluyan el "por qué" y no solo el "qué".
- Conecta a tus redactores técnicos con la comunidad más amplia para darles contexto y socializar su trabajo.
Procesos y herramientas
- Crea un proceso de documentación que dure más allá del programa Season of Docs y al que pueda contribuir toda la comunidad.
- La revisión de la documentación tardará al menos el mismo tiempo y será tan intensiva como la revisión del código. Asegúrate de dejar suficiente tiempo para ello.
Se editaron y condensaron algunas recomendaciones para mayor claridad.
Al igual que en el programa 2021, la mayoría de los redactores técnicos de Season of Docs 2022 presentaron su solicitud directamente a las organizaciones con las que trabajaron.
Problemas comunes al trabajar con redactores técnicos
Menos proyectos informaron problemas al trabajar con sus redactores técnicos en el programa 2022. El mayor problema fue que los redactores técnicos no pudieron completar el programa debido a una enfermedad, a que aceptaron un trabajo de tiempo completo o a que no pudieron cumplir con el compromiso de tiempo.
Un proyecto informó que su proyecto de documentación dependía del trabajo que se realizaba como parte de Google Summer of Code y que esas dependencias eran difíciles de administrar. Otro proyecto tuvo dificultades cuando el Ministerio de Defensa del país del redactor técnico confiscó el hardware que necesitaba documentar y no se pudo importar.
Encuestas de seguimiento
Se enviarán tres encuestas de seguimiento a los participantes de 2022 en mayo, agosto y noviembre de 2023. Actualizaremos esta sección con los resultados a medida que los recibamos.
Preguntas futuras
Como siempre, mientras más aprendemos sobre la documentación en código abierto, más queremos aprender.
En temporadas futuras, esperamos hacer lo siguiente:
- Recopilar más metadatos del proyecto para buscar correlaciones entre la antigüedad del proyecto, el tamaño de la comunidad o el idioma y las necesidades de documentación
- Analizar proyectos de documentación para ver si se pueden generalizar en plantillas compartibles
- Desarrollar una rúbrica para entrevistar a redactores técnicos en proyectos de código abierto
Si bien hay muchas preguntas que nos gustaría investigar, también queremos respetar el tiempo de los administradores y mantenedores de proyectos de código abierto que participan en Season of Docs. La prioridad principal del programa es ayudar a los proyectos a resolver sus problemas con la documentación.