Fase actual:
Casos de éxito publicados. Consulta el cronograma.
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:
- Proporcionar asistencia para proyectos de código abierto para resolver problemas del proyecto con documentación
- Brinda a los redactores técnicos oportunidades para adquirir experiencia en código abierto
- Difundir el código abierto, la documentación y la redacción técnica
- Recopila y comparte información sobre las métricas eficaces en la documentación de código abierto
Puedes encontrar más información sobre la Temporada de documentos en el sitio web del programa.
Descripción general del programa de 2022
Cómo funciona Season of Docs
En la Temporada de Documentos, las organizaciones envían una propuesta de proyecto para postularse. La propuesta del 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 el 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 información que ayude a los administradores de la Temporada de Documentos a comprender su proyecto y problema
Una vez que se acepta a los participantes en el programa, las organizaciones reclutan y contratan a sus propios redactores técnicos directamente. Season of Docs usa Open Collective para financiar a las organizaciones, y estas 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 la organización disponibles en el sitio de Season of Docs, y los pagos se pueden ver 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 caso de éxito. 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.
Momentos 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 alrededor de un 30%”. (Casbin)
“Un resultado agradable de este proyecto fue ver cómo [nuestros redactores técnicos] se convirtieron en líderes en nuestra comunidad. Ahora, ambos colaboradores dirigen reuniones del grupo de trabajo y de la comunidad, además de contribuir con el diseño y el mantenimiento de nuestros proyectos”. —moja-global
“[GSoD] nos ayudó a reclutar a dos escritores técnicos talentosos, lo cual es muy difícil en una configuración normal, que siguen siendo colaboradores activos del SO en OpenMined y con los que tuvimos una gran experiencia de trabajo”. —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 becas para personas históricamente desfavorecidas, y algunos beneficiarios usaron el nuevo manual de OpenMS para iniciar su período de pasantía de seis semanas y dieron opiniones positivas sobre el nuevo manual”. —OpenMS
Datos de resumen de 2022
En 2022, el programa aceptó 31 proyectos de 67 solicitudes, y 30 proyectos completaron el programa con éxito. De las 31 organizaciones aceptadas, 17 fueron 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 la Temporada de documentos.
Para el programa de 2022:
- El 100% de las organizaciones tuvo una experiencia positiva con el proceso de postulación
- 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 un éxito.
Acerca de las organizaciones
Las organizaciones que participaron en la Temporada de documentos de 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 de programación y frameworks, 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).
Pedimos a los proyectos que indiquen qué licencia de código abierto utilizaron.
Acerca de los proyectos de documentación
Problemas de documentación
Estos son algunos de los problemas principales que las organizaciones esperaban resolver con la documentación en el programa de 2022:
Ten en cuenta que las organizaciones pueden informar varios problemas de documentación. Para obtener más información, consulta la página de resultados de la Temporada de documentos de 2022, que incluye vínculos a las propuestas de proyectos originales y a los casos de éxito completos de cada organización.
Tipos de documentación creados
La documentación de instructivos 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 casos de éxito, se incluyen los siguientes:
- Guía de inicio rápido
- Glosario
- Preguntas frecuentes
- Base de conocimiento
- Componentes
- Contenido de blogs o redes sociales
- Guía para el encargado del mantenimiento
Algunas de estas categorías son difusas y un solo proyecto de documentación puede contener varios tipos o funciones de documentación.
Para obtener más información, consulta la página de resultados de la Temporada de documentos de 2022, que incluye vínculos a las propuestas de proyectos originales y a los casos de éxito 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
Los proyectos describieron en sus casos de éxito las métricas que usaban para medir el éxito de sus proyectos de documentación.
Las métricas principales propuestas fueron las siguientes:
Entre otras métricas propuestas, se incluyen las siguientes:
- Más solicitudes de extracción o contribuciones de documentación
- Comentarios más directos en las páginas de documentación
- Tiempo en la página
- Problemas planteados (como proxy para el uso)
- Participantes en foros
- Cantidad de socios, voluntarios o integraciones
- Porcentaje de rebote reducido
- Mayor conocimiento en la comunidad.
Debido al corto período entre terminar los proyectos de redacción técnica y enviar los casos de éxito, la mayoría de la cohorte de 2022 no pudo recopilar suficientes datos en el momento de enviar sus casos de éxito 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 información, consulta la página de resultados de la Temporada de documentos de 2022, que incluye vínculos a las propuestas de proyectos originales y a los casos de éxito completos de cada organización.
Cómo trabajar con escritores técnicos
En el programa de la Temporada de Documentos, se espera que los proyectos recluten, entrevisten, contraten y paguen directamente a los redactores técnicos. Los escritores técnicos pueden agregarse al directorio que mantiene Season of Docs en nuestro repositorio de GitHub, pero el personal de Season of Docs no revisa ni recomienda a los escritores técnicos.
Prácticas recomendadas para contratar redactores técnicos para proyectos de código abierto
Se les pidió a los proyectos que compartan 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 realiza una sesión de práctica en vivo, en lugar de solo revisar los CV.
- Valora las habilidades de comunicación escrita y oral por sobre la competencia en el lenguaje o las herramientas de tu proyecto.
- Haz preguntas directas sobre cómo el redactor técnico adquirirá los conocimientos de dominio necesarios para trabajar con tu proyecto.
- Es más probable que una persona con entusiasmo por la misión de tu proyecto y que comparta los valores fundamentales del código abierto se mantenga motivada durante todo el proyecto.
- Sé receptivo a los postulantes de todo el mundo, ya que una diversidad de puntos de vista y experiencias ayudará a tu proyecto. Sin embargo, ten en cuenta que tener escritores y mentores en demasiadas zonas horarias conflictivas puede requerir mucho esfuerzo adicional para mantener una buena comunicación.
Vacantes disponibles
- Usa un contrato que describa claramente las entregas, los cronogramas de pagos y los compromisos de tiempo específicos.
- Si tu proyecto tiene muchos aspectos desconocidos, incluye un hito para el descubrimiento o la investigación, aparte de la creación de documentación.
Coordinación y comunicación
- Mantén un registro de la reunión en el que se registren las decisiones para que todas las personas que trabajan en el proyecto puedan comprender mejor el contexto y los próximos pasos.
- Sé claro sobre qué tipo de comunicación se espera y con qué frecuencia, ya sea que se trate de llamadas semanales, correos electrónicos diarios o actualizaciones de estado en un canal de chat.
- Sé receptivo y brinda comentarios claros que incluyan el "por qué" y no solo el "qué".
- Conecta a tus redactores técnicos con la comunidad en general para darles contexto y socializar su trabajo.
Procesos y herramientas
- Crear un proceso de documentación que dure más allá del programa de la Temporada de documentos y al que pueda contribuir toda la comunidad
- La revisión de la documentación llevará al menos tanto tiempo y será tan intensiva como la revisión de código. Asegúrate de reservar suficiente tiempo para ello.
Algunas recomendaciones se editaron y condensaron para mayor claridad.
Al igual que en el programa de 2021, la mayoría de los escritores técnicos de la Temporada de Documentos 2022 se postularon directamente a las organizaciones con las que trabajaron.
Problemas comunes cuando se trabaja con redactores técnicos
Menos proyectos informaron problemas para trabajar con sus escritores técnicos en el programa de 2022. El mayor problema fue que los redactores técnicos no pudieron completar el programa debido a enfermedades, 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 estaba realizando 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 escritor técnico confiscó el hardware que este debía 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 se reciban.
Preguntas futuras
Como siempre, cuanto más aprendemos sobre la documentación de código abierto, más queremos aprender.
En las próximas temporadas, esperamos hacer lo siguiente:
- Recopila más metadatos del proyecto para buscar correlaciones entre la antigüedad del proyecto, el tamaño de la comunidad o las necesidades de idioma y documentación.
- Analizar proyectos de documentación para ver si se pueden generalizar en plantillas compartibles
- Desarrolla una rúbrica para entrevistar a redactores técnicos en proyectos de código abierto
Si bien tenemos muchas preguntas que nos gustaría investigar, también queremos respetar el tiempo de los administradores y encargados del mantenimiento de los proyectos de código abierto que participan en la Temporada de documentos. La máxima prioridad del programa es ayudar a los proyectos a resolver sus problemas con la documentación.