Fase actual:
La temporada 2021 del programa Documentos finalizó el 14 de diciembre de 2021. Consulta el cronograma.
Acerca de Season of Docs
Season of Docs es un programa de sustentabilidad administrado por la Oficina de Programas de Código Abierto de Google. Los objetivos de la temporada de Documentos son los siguientes:
- Proporcionar asistencia para proyectos de código abierto para resolver problemas del proyecto con documentación
- Brinda a los escritores técnicos oportunidades para ganar experiencia en código abierto
- Aumentar el conocimiento del 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 2021
Cambios en el programa de 2021
En 2019 y 2020, las organizaciones y los escritores técnicos se postularon al programa de la Temporada de documentos por separado, y los administradores del programa de la Temporada de documentos los emparejaron con las organizaciones. Las organizaciones proporcionaron mentores para que trabajaran con los escritores técnicos, quienes recibieron un subsidio 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, cambiando el enfoque hacia la medición de los resultados de la documentación y permitiendo más flexibilidad para las organizaciones y los redactores técnicos.
- Las organizaciones que se postularon con propuestas de proyectos, incluidos un presupuesto y métricas propuestas
- Los escritores técnicos ya no se postulan a través de Google para asignarse a organizaciones, sino que lo hacen directamente a las organizaciones aceptadas.
- Las organizaciones aceptadas recibieron subvenciones a través de Open Collective, que utilizaron para pagar a los redactores técnicos.
- Las organizaciones establecieron la compensación de los escritores técnicos.
- Las organizaciones enviaron evaluaciones finales y casos de éxito, y respondieron encuestas de seguimiento.
Hallazgos generales de 2021
Organizaciones
- Los cambios en el programa de 2021 provocaron que menos organizaciones se postularan (observamos que un 30% menos de organizaciones se postulaban en 2021 en comparación con 2020), pero los administradores de la organización de 2021 estuvieron un poco más satisfechos con el programa que los de 2020 (93% frente a 91%).
Problemas, tipos de documentos y métricas
- La mayoría de los proyectos se enfocaron en crear documentación para reducir la carga del encargado de mantenimiento (mediante 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 crearon contenido instructivo.
- Más del 50% de las organizaciones aceptadas consideraron que su documentación actual era insuficiente, desorganizada o desactualizada.
- Por lo general, los proyectos querían medir la eficacia de su documentación a través de interacciones, en especial, menos problemas planteados y más visitantes a los documentos y participación en los proyectos.
- Hasta noviembre de 2022, 25 de 30 proyectos respondieron:
- 18 proyectos declararon que cumplieron con sus métricas originales
- 5 proyectos cumplieron con las métricas revisadas
- 2 proyectos dijeron que aún era demasiado pronto para saberlo
Participación en el programa
- Reclutar, contratar y pagar a los redactores técnicos fue la parte más difícil del programa para los administradores de la organización.
- A noviembre de 2022, 24 de las 30 organizaciones respondieron lo siguiente:
- 18 organizaciones aún trabajaban con sus redactores técnicos de la Temporada de documentos (ya sea como colaboradores continuos o como recursos para responder preguntas).
- 4 organizaciones trabajaban con sus redactores técnicos de la Temporada de Documentos en un puesto remunerado
- 18 organizaciones aún trabajaban con sus redactores técnicos de la Temporada de documentos (ya sea como colaboradores continuos o como recursos para responder preguntas).
Puntos destacados de 2021
- Varios proyectos indicaron que su escritor técnico tenía la intención de seguir trabajando con su proyecto después de que finalice el programa de la Temporada de documentos.
- Metanorma hizo que muchos redactores técnicos calificados solicitaran fondos suficientes para contratar a otro escritor para que trabajara junto con la temporada de escritores admitidos 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 participaran en la documentación del proyecto.
Datos de resumen de 2021
En 2021, 82 organizaciones presentaron la solicitud y 30 organizaciones de código abierto se aceptaron al programa. (Consulta los criterios de selección en la Guía para crear tu solicitud). Puedes encontrar la lista completa de organizaciones participantes en el sitio web de la Temporada de Documentos. 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 de 2021 representaron una amplia variedad de proyectos de código abierto. La cohorte de 2021 incluyó lo siguiente:
- Proyectos de lenguaje extensos, como Julia, Perl y R
- Proyectos en educación, clima, fintech, atención médica, servicios de bibliotecas, aprendizaje automático, espectrometría de masas, contratos públicos y robótica
- Proyectos enfocados en desarrolladores, incluidas 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 fueron 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, 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 utilizaban.
Los problemas de documentación que describen las organizaciones de 2021 son muy comunes en los proyectos de código abierto y en la documentación técnica en general.
Entre los principales problemas que las organizaciones esperaban resolver en el programa de 2021, se incluyen los siguientes:
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 2021, que incluye 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 que se mencionan 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 sobre usuarios, Léame, Base de conocimiento.
Algunas de estas categorías son difusas y un solo proyecto de documentación puede contener varios tipos o funciones de documentación.
Varios proyectos a los que se hace referencia específicamente con el framework Diátaxis como guía para planificar sus tipos de documentación.
Para obtener más información, consulta la página de resultados de la Temporada de documentos de 2021, que incluye 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 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:
Otras métricas propuestas incluían estrellas de GitHub, tiempo en la página, conversiones de listas de distribución, pruebas cualitativas de usuarios, cantidad de participantes en foros, cantidad de socios, voluntarios o integraciones.
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 2021 no pudo recopilar suficientes datos para determinar si se cumplieron o no sus métricas iniciales.
Para obtener más información, consulta la página de resultados de la Temporada de documentos de 2021, que incluye vínculos a casos de éxito completos de cada organización.
Cómo trabajar con escritores técnicos
El mayor cambio en el programa de la Temporada de documentos de 2021 fue la forma en que los proyectos trabajaban con los escritores técnicos. En temporadas anteriores, los redactores técnicos se postulaban directamente a Google, y los administradores del programa los asignaban a proyectos. Además, recibían un sueldo fijo directamente de Google.
En 2021, los redactores técnicos se postularon directamente a los proyectos, que establecieron el presupuesto para su compensación, y los pagos se realizaron a través del fondo de 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 o la contratación de redactores técnicos, y muchos proyectos señalaron que esta parte del proceso es la que necesita más asistencia. En respuesta a estos comentarios, el equipo de la Temporada de Documentos agregó documentación para crear acuerdos de escritores técnicos a la guía del programa.
Recomendaciones de contratación
Se les 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:
- Comparte los materiales de reclutamiento para escritores técnicos lo antes posible, incluso antes de que te acepten en el programa. Pídele a la comunidad que recomiende posibles candidatos.
- Compartir el contenido ampliamente fuera de los canales del proyecto Usa un lenguaje inclusivo y anima directamente a los candidatos de entornos poco representados a postularse.
- Comprende qué herramientas son esenciales para tu proceso de creación de documentación y recluta a redactores técnicos con experiencia en el uso de esas herramientas.
- Crea expectativas claras para el escritor técnico sobre los entregables y los eventos importantes, los canales de comunicación y los puntos de control, y los procesos y los tiempos de pago.
- Considera invertir en los miembros de la comunidad y ayudarlos a crecer como escritores técnicos con el escritor técnico de la Temporada de Documentos para brindar orientación y capacitación.
- Reserva más tiempo del que esperas para integrar a los escritores técnicos, responder preguntas y brindar asistencia durante el programa, especialmente si el escritor técnico no tiene experiencia previa en el dominio de tu proyecto.
- Documenta tu proceso de reclutamiento, contratación y capacitación para usarlo en proyectos futuros.
(Nota: No todos los proyectos indicaron en sus casos de éxito dónde reclutaron a sus candidatos a redactores técnicos).
Problemas comunes cuando se trabaja con redactores técnicos
Los redactores técnicos de varios proyectos tuvieron que abandonar el proyecto debido al COVID-19 o a otras enfermedades, o por responsabilidades familiares relacionadas con la pandemia. Algunos proyectos informaron problemas de comunicación relacionados con discrepancias de zona horaria o problemas de conectividad a Internet.
Los proyectos descubrieron que subestimaron las dificultades que implicaba la integración en sus comunidades o la configuración de la cadena de herramientas de documentos de su proyecto.
Algunos proyectos tuvieron retrasos en el pago a sus redactores técnicos debido a problemas bancarios con Open Collective o porque los países de origen de los redactores 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 de la 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 su propuesta y caso de éxito seguían activos. La encuesta también incluyó preguntas sobre el éxito de sus proyectos (según lo determinado por las métricas que establecieron en sus casos de éxito) y la participación y compensación continuas de los redactores técnicos del proyecto:
- ¿Todavía trabajas con tu escritor técnico de la Temporada de Documentos?
- Si el escritor técnico sigue trabajando en tu proyecto, ¿reciben alguna compensación?
- En este punto, ¿crees que tu proyecto de documentación es un éxito?
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 obtener información sobre lo siguiente:
- Si los dominios de proyectos se correlacionan con la elección de doctype o de métrica
- Qué prácticas de contratación y integración de redactores técnicos son más eficaces para completar el proyecto y retener a los redactores 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 del mantenimiento de 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.