Fase actual:
La temporada de Documentos 2021 finalizó el 14 de diciembre de 2021. Consulta el cronograma.
Acerca de la temporada de Documentos
Season of Docs es un programa de sustentabilidad administrado por la Google Open Source Programs Office. Los objetivos de la temporada de Documentos son los siguientes:
- Brindar apoyo en proyectos de código abierto para resolver problemas de estos 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
- Recopilar y compartir información sobre métricas eficaces en la documentación de código abierto
Para obtener más información sobre la temporada de Documentos, visita el sitio web del programa.
Descripción general del programa de 2021
Cambios en el programa para 2021
En 2019 y 2020, las organizaciones y los escritores técnicos presentaron una solicitud para participar en el programa Season of Docs por separado, y los administradores del programa Season of Docs vincularon a los técnicos con organizaciones. Las organizaciones proporcionaban mentores para que trabajaran con escritores técnicos, que recibían un salario por su trabajo en función de su ubicación. El programa midió si los escritores técnicos, los mentores y los administradores de la organización estaban satisfechos con su participación en el programa, pero no midió los resultados de la documentación.
En 2021, el equipo de Season of Docs realizó cambios significativos en el programa, por lo que cambió el enfoque hacia la medición de los resultados de la documentación y permitió más flexibilidad para las organizaciones y los escritores técnicos.
- Organizaciones que se postulan con propuestas de proyectos, incluidos un presupuesto y las métricas propuestas
- Los escritores técnicos ya no presentaron solicitudes a través de Google para coincidir con organizaciones, sino que se postuló directamente a las organizaciones aceptadas.
- Las organizaciones aceptadas recibieron subsidios a través de Open Collective, y los usaron para pagarles a escritores técnicos.
- Las organizaciones fijaban la remuneración para los escritores técnicos
- Las organizaciones enviaron evaluaciones finales y casos de éxito, y respondieron encuestas de seguimiento.
Resultados generales de 2021
Organizaciones
- Los cambios en el programa de 2021 hicieron que menos organizaciones envíen solicitudes (observamos un 30% menos de organizaciones que se postularon en 2021 en comparación con 2020), pero los administradores de las organizaciones de 2021 estaban un poco más conformes con el programa que los administradores de 2020 (93% contra 91%).
Problemas, tipos de documentos y métricas
- La mayoría de los proyectos se centraron en crear documentación para reducir la carga de los encargados de mantener (a través de la reducción de problemas o preguntas) o aumentar la participación en el proyecto (ya sea por parte de los usuarios o colaboradores del proyecto).
- El 50% de las organizaciones aceptadas creó instructivos o contenido instructivo.
- Más del 50% de las organizaciones aceptadas consideraba que su documentación actual carecía, estaba desorganizada o estaba desactualizada.
- En general, los proyectos querían medir la eficacia de su documentación a través de interacciones, en especial, se plantearon menos problemas y más visitantes a los documentos y a la participación en los proyectos.
- Hasta noviembre de 2022, 25 de 30 proyectos respondieron:
- 18 proyectos indicaron que habían alcanzado sus métricas originales
- 5 proyectos cumplieron con las métricas revisadas
- 2 proyectos indicaron que todavía era demasiado pronto para saberlo
Participación en el programa
- Reclutar, contratar y pagar escritores técnicos fue la parte más difícil del programa para los administradores de la organización.
- Hasta noviembre de 2022, 24 de 30 organizaciones respondieron:
- 18 organizaciones seguían trabajando con los escritores técnicos de la temporada de Documentos (ya sea como colaboradores continuos o como recurso para responder preguntas).
- 4 organizaciones trabajaban con los escritores técnicos de la temporada de Documentos en un rol pagado.
- 18 organizaciones seguían trabajando con los escritores técnicos de la temporada de Documentos (ya sea como colaboradores continuos o como recurso para responder preguntas).
Momentos destacados de 2021
- Varios proyectos indicaron que su escritor técnico tenía la intención de continuar trabajando con su proyecto después del final del programa de temporada de Documentos.
- Metanorma pidió tantos escritores técnicos calificados que encontraron fondos equivalentes para contratar a otro que trabajara junto con el de la temporada de escritores apoyados por Documentos durante el programa.
- Moja Global descubrió que la comunidad estaba muy involucrada en la documentación y creó un nuevo grupo de trabajo de documentación para permitir que más colaboradores participen en la documentación del proyecto.
Resumen de datos de 2021
En 2021, se presentaron 82 organizaciones y se aceptaron 30 organizaciones de código abierto para el programa. (Consulta la guía Cómo crear tu aplicación para conocer los criterios de selección). La lista completa de las organizaciones participantes se encuentra en el sitio web de Season of Docs. Las 30 organizaciones aceptadas enviaron su informe de caso de éxito final para completar su participación en el programa de 2021.
Acerca de las organizaciones
Las organizaciones que participaron en la temporada de Documentos 2021 representaron una variedad diversa de proyectos de código abierto. La cohorte de 2021 incluyó lo siguiente:
- Proyectos de lenguaje extensos, como Julia, Perl y R
- Proyectos de educación, clima, tecnología financiera, atención médica, servicios de biblioteca, aprendizaje automático, espectrometría de masas, contratos públicos y robótica
- Proyectos centrados en los desarrolladores, como herramientas de ingeniería del caos, fuzzers, SDK de chatbot, canalizaciones de análisis de composición de software, herramientas de supervisión del rendimiento y herramientas de programación visual
- Proyectos de documentación para herramientas de documentación, como Redocly y Metanorma
Los proyectos del ecosistema de Python eran la subcategoría más grande. La cohorte de 2021 incluyó ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite y SymPy.
No recopilamos metadatos sobre los proyectos (como la fecha de fundación, la distribución geográfica de los colaboradores, el número de colaboradores o el tamaño de la base de usuarios).
Pedimos a los proyectos que indicaran qué licencia de código abierto usaban.
Los problemas de documentación señalados por las organizaciones de 2021 son problemas muy comunes tanto en los proyectos de código abierto como en la documentación técnica en general.
Estos son algunos de los principales problemas que las organizaciones esperaban resolver en el programa de 2021:
Ten en cuenta que las organizaciones pueden informar varios problemas de documentación. Si quieres obtener información más específica, consulta la página de resultados de la temporada de Documentos 2021, que contiene vínculos a casos de éxito completos de cada organización.
Tipos de documentación creados
Los instructivos fueron el tipo de documentación más mencionado en los casos de éxito de 2021.
Otros tipos de documentación mencionados en los casos de éxito incluyen canalización de documentos como código, diagrama, glosario, guía de estilo, preguntas frecuentes, internacionalización, codelab, modelo de contenido, módulos, documentación de conceptos, mensajes de error, investigación de usuarios, archivo Léame y base de conocimiento.
Algunas de estas categorías son confusas y un solo proyecto de documentación puede contener varios tipos de documentación o características.
Varios proyectos a los que se hace referencia específicamente mediante el framework de Diátaxis como guía para planificar sus tipos de documentación
Si quieres obtener información más específica, consulta la página de resultados de la temporada de Documentos 2021, que contiene vínculos a casos de éxito completos de cada organización.
Presupuestos
En 2021, la solicitud de presupuesto promedio fue de USD 10,200 y la mediana fue de USD 10,000. Solo tres organizaciones solicitaron y recibieron la subvención máxima posible (USD 15,000) y otras tres solicitaron la subvención más baja posible (USD 5,000).
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 métricas propuestas más importantes fueron las siguientes:
Otras métricas propuestas incluyen las estrellas de GitHub, el tiempo de permanencia en la página, las conversiones de la lista de distribución, las pruebas cualitativas de usuarios, la cantidad de participantes en foros y la cantidad de socios, voluntarios e integraciones.
Debido a la corta ventana entre la finalización de los proyectos de redacción técnica y el envío de los casos de éxito, la mayor parte de la cohorte de 2021 no pudo recopilar suficientes datos para determinar si se cumplían o no sus métricas iniciales.
Si quieres obtener información más específica, consulta la página de resultados de la temporada de Documentos 2021, que contiene vínculos a casos de éxito completos de cada organización.
Trabaja con escritores técnicos
El mayor cambio que se realizó en el programa Temporada de Documentos en 2021 implicó cómo funcionaban los proyectos con los escritores técnicos. En temporadas anteriores, los escritores técnicos presentaron solicitudes directamente a Google, los administradores del programa hicieron coincidir los proyectos y recibieron un subsidio fijo directamente de Google.
En 2021, los redactores técnicos se postularon directamente a los proyectos y estos establecieron el presupuesto para una remuneración técnica a través del fondo Open Collective de la temporada de Documentos.
La mayoría de los proyectos que participaron en el programa de 2021 tenían poca o ninguna experiencia en el reclutamiento de escritores técnicos, y muchos proyectos indicaron que esta parte del proceso necesita más apoyo. En respuesta a estos comentarios, el equipo de Season of Docs agregó documentación para crear acuerdos técnicos de redactor a la guía del programa.
Recomendaciones de contratación
Se pidió a los proyectos que hicieran recomendaciones para otros proyectos interesados en participar en la temporada de Documentos. Las principales recomendaciones de contratación fueron las siguientes:
- Comparte los materiales de reclutamiento para escritores técnicos lo antes posible, incluso antes de que te acepten en el programa. Pídele a tu comunidad que recomiende posibles candidatos.
- Compartirla de forma amplia fuera de los canales del proyecto. Usa un lenguaje inclusivo y alienta directamente a candidatos de orígenes subrepresentados a que se postulen.
- Comprende qué herramientas son esenciales para tu proceso de creación de documentación y contrata escritores técnicos con experiencia en el uso de esas herramientas.
- Crea expectativas claras para el escritor técnico sobre los entregables e hitos, los canales de comunicación y los controles, y los procesos y los plazos de los pagos.
- Considera invertir en los miembros de la comunidad y ayudarlos a crecer como escritores técnicos. Para ello, usa la función de escritores técnicos de Season of Docs para ofrecer mentoría y asesoramiento.
- Invierte más tiempo del que esperas para integrar a escritores técnicos, responder preguntas y brindar asistencia durante el programa, especialmente si el redactor técnico no tiene experiencia previa en el dominio de tu proyecto.
- Documenta el proceso de reclutamiento, contratación e integración para utilizarlos en proyectos futuros.
(Nota: No todos los proyectos indican en los casos de éxito en los que contrataron candidatos para escritores técnicos).
Problemas comunes al trabajar con escritores técnicos
Los escritores técnicos de varios proyectos tuvieron que abandonar la organización debido al COVID y otras enfermedades, o a responsabilidades familiares relacionadas con la pandemia. Algunos proyectos informaron problemas de comunicación relacionados con discrepancias de zonas horarias o problemas de conectividad a Internet.
En los proyectos, descubrieron que subestimaban las dificultades que implicaba integrarse a sus comunidades o establecer el conjunto de herramientas de documentos de sus proyectos.
Algunos proyectos presentaron retrasos en los pagos a sus escritores técnicos debido a problemas bancarios con Open Collective o porque los países de origen de los escritores tenían restricciones de pago.
La documentación del programa sobre las tarifas de Open Collective no era clara: Google cubrió las tarifas de transacción de Open Collective para la transferencia inicial de fondos a los proyectos, pero no las tarifas de transacción impuestas por otros canales de pago (como las tarifas de conversión de moneda). Trabajaremos para aclarar esto en la documentación de los programas futuros.
Encuestas de seguimiento
Como parte del programa Temporada de Documentos, se les pidió a los proyectos que participaran en encuestas de seguimiento. Se enviaron tres encuestas en mayo, agosto y noviembre de 2022.
En la encuesta de seguimiento, se les pidió a los proyectos que confirmaran que los vínculos de la propuesta y los casos prácticos aún estaban activos. La encuesta también incluyó preguntas sobre el éxito de sus proyectos (según lo determinado por las métricas que establecieron en el caso práctico) y la participación continua y la compensación de los redactores técnicos del proyecto:
- ¿Sigues trabajando con el escritor técnico de la Temporada de Documentos?
- Si tu escritor técnico sigue trabajando en tu proyecto, ¿recibirás algún tipo de remuneración?
- En este punto, ¿sientes que tu proyecto de documentación es exitoso?
Preguntas futuras
Como siempre, cuanto más aprendamos sobre la documentación en código abierto, más aprenderemos. En las próximas temporadas, esperamos aprender lo siguiente:
- Si los dominios de proyecto se correlacionan con la elección del tipo de documento o de la métrica
- Qué prácticas de incorporación y contratación de escritores técnicos son más efectivas para la finalización del proyecto y la retención de escritores técnicos
- Cronogramas razonables para medir la eficacia de la documentación
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 documentación.