Fase actual:
Desarrollo de la documentación. Consulta el cronograma.
Season of Docs es un programa de sustentabilidad administrado por la Google Open Source Programs Office (Oficina de Programas de Código Abierto de Google). Los objetivos de la temporada de Documentos son:
- Brindar apoyo a proyectos de código abierto para resolver problemas de proyectos con documentación
- Brinda a los escritores técnicos oportunidades para ganar experiencia en código abierto.
- Aumentar el reconocimiento del código abierto, la documentación y la redacción técnica
- Recopila y comparte información sobre métricas eficaces en la documentación de código abierto
Obtenga 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 la temporada de Documentos
En Season of Docs, las organizaciones se postulan 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 utilizará la documentación para ayudar a resolver su problema
- Cómo medirá el proyecto la eficacia de su documentación (métricas)
- Un cronograma para el trabajo
- El presupuesto de un proyecto
- Cualquier información adicional, como la experiencia de la organización en programas similares o cualquier otro dato que ayude a los administradores de Temporada de Documentos a comprender su proyecto y problema
Una vez aceptadas en el programa, las organizaciones reclutan y contratan a sus propios escritores técnicos directamente. Season of Docs usa Open Collective para financiar a las organizaciones, y las organizaciones les pagan a los redactores técnicos a través de Open Collective. Los presupuestos y pagos de los proyectos son transparentes; los presupuestos se incluyen en las propuestas de proyectos de la organización, que están disponibles en el sitio de Season of Docs, y los pagos, en la cuenta de Open Collective de la serie Season of Docs.
Se considera que las organizaciones completaron con éxito el programa cuando envían el informe de su caso práctico. También se les solicita a las organizaciones que completen evaluaciones mensuales durante el programa y tres encuestas de seguimiento trimestrales durante el año siguiente a la finalización del programa.
Aspectos destacados de 2022
"Después de la publicación del 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 maravilloso de este proyecto fue observar a [nuestros escritores técnicos] crecer en roles de liderazgo en nuestra comunidad. Ambos colaboradores ahora lideran reuniones de grupos de trabajo y comunidades, y contribuyen al diseño y 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 organización habitual, que siguen siendo colaboradores activos de SO para OpenMined y con los que tuvimos una gran experiencia laboral”. —OpenMined
“Además, el nuevo manual es mucho más sencillo para los novatos en la espectrometría de masas computacional. Para ilustrar este punto, la subvención de CZI también otorga subsidios a personas históricamente desfavorecidas, y algunos beneficiarios utilizaron el nuevo manual de OpenMS para iniciar su período de pasantía de seis semanas y proporcionaron revisiones positivas del nuevo manual”. —OpenMS
Resumen de datos de 2022
En 2022, el programa Temporada de Documentos aceptó 31 proyectos de 67 solicitudes y 30 proyectos completaron con éxito el programa. De las 31 organizaciones aceptadas, 17 organizaciones fueron solicitudes repetidas.
Los 31 proyectos aceptados contrataron a 58 escritores técnicos. Más de 190 escritores técnicos expresaron su interés en participar en el programa agregando su información de contacto y enlaces a sus portfolios 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 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 sintieron que su proyecto de documentación fue exitoso
Acerca de las organizaciones
Las organizaciones que participaron en Season of Docs 2022 representaron un rango diverso de proyectos de código abierto. La cohorte de 2022 incluyó lo siguiente:
- Herramientas de desarrollo, como AsyncAPI y SpyderIDE
- Lenguajes y frameworks 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
- Los 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 colaboradores, el número de colaboradores o el tamaño de la base de usuarios).
Sí 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 de 2022, se incluyen los siguientes:
Ten en cuenta que las organizaciones pueden informar varios problemas de documentación. Para obtener más detalles, consulta la página de resultados de la Temporada de Documentos de 2022, que incluye vínculos a las propuestas de proyectos originales y los casos de éxito completos de cada organización.
Tipos de documentación que se crean
La documentación práctica fue el tipo de documentación más mencionado en los casos de éxito de 2022.
Otros tipos de documentación mencionados en los casos prácticos incluyen los siguientes:
- Guía de inicio rápido
- Glosario
- Preguntas frecuentes
- Base de conocimiento
- Componentes
- Contenido de blog o redes sociales
- Guía para encargados de mantenimiento
Algunas de estas categorías son confusas y un solo proyecto de documentación puede contener varios tipos o características de documentación.
Para obtener más detalles, consulta la página de resultados de la Temporada de Documentos de 2022, que incluye vínculos a las propuestas de proyectos originales y los casos de éxito completos de cada organización.
Presupuestos
La solicitud de presupuesto promedio fue de USD 11,679 y la mediana, 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 mil).
Las métricas
Los proyectos descritos en los casos prácticos las métricas que utilizaban para medir 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 contribuciones o solicitudes de extracción de documentación
- Comentarios más directos en las páginas de documentación
- Tiempo transcurrido en la página
- Problemas que se presentan (como proxy para usar)
- Participantes en foros
- Cantidad de socios, voluntarios o integraciones
- Porcentaje de rebote reducido
- Mayor conciencia en la comunidad.
Debido a la corta ventana entre finalizar los proyectos de escritura técnica y enviar los casos prácticos, la mayor parte de la cohorte de 2022 no había podido recopilar suficientes datos al momento de enviar sus casos de éxito para determinar si se cumplían 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 los proyectos que alcanzaron sus métricas o revisaron sus métricas.
Para obtener más detalles, consulta la página de resultados de la Temporada de Documentos de 2022, que incluye vínculos a las propuestas de proyectos originales y los casos de éxito completos de cada organización.
Trabajar con escritores técnicos
En el programa Temporada de Documentos, se espera que los proyectos recluten, entrevisten, contraten a escritores técnicos y les paguen directamente. 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 escritores técnicos.
Prácticas recomendadas a la hora de contratar escritores técnicos para proyectos de código abierto
Se pidió a los proyectos que compartieran sus mejores prácticas para reclutar, contratar y trabajar con escritores técnicos. Las recomendaciones principales fueron las siguientes:
Reclutamiento
- Entrevista a menos candidatos y aprovecha una sesión de práctica en vivo, en lugar de solo revisar los CV.
- Valora las habilidades de comunicación oral y escrita que la competencia en el lenguaje o las herramientas de tu proyecto
- Haz preguntas directas sobre cómo el escritor 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 comparte los valores fundamentales de código abierto se mantenga motivada durante todo el proyecto.
- Debes estar abierto a solicitantes de todo el mundo, ya que la diversidad de puntos de vista y antecedentes ayudará a tu proyecto; pero ten en cuenta que tener escritores y mentores en demasiadas zonas horarias en conflicto puede requerir mucho esfuerzo adicional para mantener una buena comunicación.
Vacantes disponibles
- Usa un contrato que detalle claramente las entregas, los cronogramas de pagos y los plazos 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 la documentación.
Coordinación y comunicación
- Mantén un registro de las decisiones en una reunión para que todos los que trabajan en el proyecto comprendan el contexto y los próximos pasos con mayor facilidad.
- Explica con claridad qué se espera de la comunicación 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 “por qué” y no solo “qué”.
- Conectar a los escritores técnicos con la comunidad más amplia para darles contexto y para socializar su trabajo
Procesos y herramientas
- Crear un proceso de documentación que durará más allá del programa de la temporada de Documentos y al que toda la comunidad pueda contribuir
- La revisión de la documentación tardará al menos tanto tiempo como la revisión de código, así que asegúrate de contar con el tiempo necesario.
Algunas recomendaciones se editaron y se resumieron para mayor claridad.
Al igual que en el programa de 2021, la mayoría de los escritores técnicos de Season of Docs 2022 se postularon directamente a las organizaciones con las que trabajaban.
Problemas comunes en el trabajo con escritores técnicos
Menos proyectos informaron problemas de trabajo con sus escritores técnicos en el programa de 2022. Que los escritores técnicos no pudieran completar el programa fue el mayor problema, debido a una enfermedad, haber aceptado un trabajo a tiempo completo o incapaz de cumplir con el compromiso de tiempo.
Un proyecto informó que su proyecto de documentación dependía de que las tareas se realizaran como parte de Google Summer of Code y que esas dependencias eran difíciles de administrar. Otro proyecto tuvo dificultades cuando el hardware que su escritor técnico necesitaba documentar fue confisado por el Ministerio de Defensa en el país del escritor y no pudo importarse.
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 aprendamos sobre la documentación en código abierto, más queremos aprender.
En las próximas temporadas, esperamos lograr lo siguiente:
- Recopilar 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
- Desarrollar una rúbrica para entrevistar a escritores técnicos en proyectos de código abierto
Aunque hay muchas preguntas que nos gustaría investigar, también queremos respetar el tiempo de los administradores y encargados de mantenimiento de proyectos de código abierto que participan en Season of Docs. La máxima prioridad del programa es respaldar los proyectos para que resuelvan sus problemas con la documentación.