Fase actual:
La temporada de Documentos de Google 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 (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 2021
Cambios en el programa de 2021
En 2019 y 2020, las organizaciones y los escritores técnicos se postularon por separado al programa Season of Docs, y los administradores del programa Season of Docs asignaron a los escritores técnicos. Las organizaciones proporcionaban mentores para que trabajaran con escritores técnicos, quienes recibían una remuneración 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, lo que cambió el enfoque a medir los resultados de la documentación y les brindó más flexibilidad a las organizaciones y los escritores técnicos.
- Organizaciones que se postulan con propuestas de proyectos, incluidos un presupuesto y métricas propuestas
- Los escritores técnicos ya no solicitaron acceso a través de Google para que se los asigne a organizaciones, sino directamente a las organizaciones aceptadas.
- Las organizaciones aceptadas recibieron subsidios a través de Open Collective, los cuales utilizaron para pagarles a escritores técnicos.
- Las organizaciones establecieron la remuneració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 envíen solicitudes (observamos un 30% menos de organizaciones que lo hicieron en 2021 en comparación con 2020), pero los administradores de la organización de 2021 se sintieron un poco más satisfechos con el programa que los administradores de 2020 (93% frente a 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 crearon instructivos o contenido instructivo.
- Más del 50% de las organizaciones aceptadas considera que su documentación actual carece, está desorganizada o está desactualizada.
- En general, los proyectos querían medir la eficacia de su documentación a través de interacciones, en especial, la cantidad de problemas planteados y más visitantes a los documentos y la participación en proyectos.
- Hasta noviembre de 2022, respondieron 25 de 30 proyectos:
- 18 proyectos indicaron que habían alcanzado sus métricas originales
- 5 proyectos habían alcanzado las métricas revisadas
- 2 proyectos indicaron que aún era demasiado pronto para saberlo
Participación en el programa
- Reclutar, contratar y pagar a escritores técnicos fue la parte más difícil del programa para los administradores de la organización.
- Hasta noviembre de 2022, respondieron 24 de 30 organizaciones:
- 18 organizaciones seguían trabajando con los redactores 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 Season of Docs de forma remunerada.
- 18 organizaciones seguían trabajando con los redactores 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 seguir trabajando con su proyecto después del final del programa Temporada de Documentos
- Metanorma pidió tantos escritores técnicos calificados que encontraron fondos coincidentes para contratar a otro que trabajara codo a codo con el escritor apoyado por la temporada de 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 resumidos de 2021
En 2021, se presentaron 82 organizaciones y 30 organizaciones de código abierto se aceptaron en el programa. (Consulta la guía Crea 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 Season of Docs 2021 representaron un rango diverso 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, salud, servicios de biblioteca, aprendizaje automático, espectrometría de masas, contratos públicos y robótica
- Proyectos enfocados en desarrolladores, incluidas herramientas de ingeniería de caos, fuzzers, SDK de chatbots, 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 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.
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. Para obtener más detalles, 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 que se crean
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 sobre usuarios, readme y base de conocimiento.
Algunas de estas categorías son confusas y un solo proyecto de documentación puede contener varios tipos o características de documentación.
Varios proyectos a los que se hace referencia específicamente con el marco de trabajo Diátaxis como guía para planificar sus tipos de documentación
Para obtener más detalles, 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, 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 principales métricas propuestas fueron las siguientes:
Otras métricas propuestas incluyen las estrellas de GitHub, el tiempo dedicado a la página, las conversiones de listas de distribución, las pruebas cualitativas de usuarios, la cantidad de participantes en foros y la cantidad de socios, voluntarios o integraciones.
Debido a la corta ventana entre finalizar los proyectos de escritura técnica y enviar los casos de éxito, la mayor parte de la cohorte de 2021 no había podido recopilar suficientes datos para determinar si se cumplían o no sus métricas iniciales.
Para obtener más detalles, 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.
Trabajar con escritores técnicos
El mayor cambio en el programa Temporada de Documentos en 2021 implicó la manera en que los proyectos funcionaban con los escritores técnicos. En temporadas anteriores, los escritores técnicos se postulaban directamente a Google, los administradores del programa asignaban proyectos a ellos y les pagaban un subsidio fijo directamente de Google.
En 2021, los escritores técnicos se postularon directamente a los proyectos y estos establecieron el presupuesto de la compensación para los escritores técnicos, con pagos realizados 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 o contratación de escritores técnicos, y muchos proyectos señalaron esta parte del proceso como una que 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 hayan aceptado en el programa. Pídele a tu comunidad que recomiende posibles candidatos.
- Compartir ampliamente fuera de los canales del proyecto. Usa un lenguaje inclusivo y alienta directamente a los candidatos de entornos 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 registros, y los procesos y plazos de pago.
- Considera invertir en los miembros de la comunidad y ayúdalos a crecer como escritores técnicos. Para ello, usa la función de escritor técnico de Season of Docs para ofrecer tutoría y capacitación.
- Asigna más tiempo del que esperas para integrar a 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 e incorporación para utilizarlos en proyectos futuros.
(Nota: No todos los proyectos se indican en los casos de éxito en los que reclutaron a sus candidatos para escritores técnicos).
Problemas comunes en el trabajo con escritores técnicos
Los escritores técnicos de varios proyectos tuvieron que abandonar el proceso debido al COVID y otras enfermedades, o debido a 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.
En los proyectos, se descubrió que subestimaron las dificultades que implica integrarse a sus comunidades o configurar el conjunto de herramientas de documentos de su proyecto.
Algunos proyectos tenían demoras en el pago de los 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 cubría 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 dejar esto más claro en la documentación para 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 a la propuesta y al caso práctico 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 su 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 Temporada de Documentos?
- Si el escritor técnico sigue trabajando en tu proyecto, ¿se lo compensa de alguna manera?
- En este punto, ¿crees 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 queremos aprender. En temporadas futuras, esperamos aprender lo siguiente:
- Si los dominios de los proyectos se correlacionan con la elección de tipo de documento o de métrica
- Qué prácticas de contratación e incorporación de escritores técnicos son más eficaces para la finalización del proyecto y la retención del redactor técnico
- 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 la documentación.