Proyecto CERN-HSF

En esta página, se incluyen los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.

Resumen del proyecto

Organización de código abierto:
CERN‐HSF
Redactor técnico:
Ariadne
Nombre del proyecto:
Rucio: Moderniza (reestructura y reescribe) la documentación de Rucio
Duración del proyecto:
Duración estándar (3 meses)

Project description

Resumen: El framework de Rucio se desarrolló con el objetivo de administrar y organizar grandes volúmenes de datos científicos distribuidos geográficamente en centros de datos heterogéneos. El framework ofrece capacidades como la recuperación de datos distribuidos y la replicación adaptable, y es altamente escalable, modular y extensible. Los consumidores de la documentación de ese servicio tendrían diversos orígenes y requisitos variados cuando accedan a ella. Por lo tanto, una buena documentación para un servicio de este tipo debe simplificar su adopción y uso para los usuarios finales y, al mismo tiempo, ser una referencia para los problemas y la solución de problemas comunes.

Sin esa documentación, habría obstáculos importantes en el uso eficiente y eficaz. Esto podría aumentar los costos de asistencia y representar un riesgo de reputación para la identidad corporativa del producto. Después de todo, la documentación es un modo de comunicación. Por lo tanto, garantizar que la comunicación esté encapsulada en un marco de trabajo accesible y fácil de administrar y, al mismo tiempo, que siga siendo relevante con la versión adecuada, significa que nos comunicamos para lograr el éxito.

En el momento de escribir este artículo, el framework de Rucio se usó para alimentar los requisitos de alta energía de los experimentos ATLAS y CMS en el LHC. También se está utilizando para satisfacer las necesidades de las comunidades científicas diversas más allá de los LHC, como la astrofísica, lo que hace que la documentación sea lo más relevante y accesible posible. Con la ayuda de este proyecto, el CERN quiere permitir que los usuarios finales de Rucio tengan una experiencia fluida mientras usan el framework, ya que proporciona una vista centralizada para acceder a toda la documentación relevante.

Estado actual: A partir de hoy, la documentación para el usuario se encuentra en diferentes lugares y en varios formatos, incluidos artículos científicos, readthedocs.io con la fuente en el código, Google Drive, GitHub, DockerHub o wikis. Las múltiples fuentes generan problemas con el seguimiento de las versiones y la exactitud de la documentación. Además, un modelo descentralizado de documentación plantea obstáculos significativos a la hora de navegar y mostrar información relevante para un caso de uso determinado. Especialmente en el caso de los Wikis, la información proporcionada para un experimento en particular podría aplicarse también a otras instancias que residen en la misma fuente o en otras. Sin embargo, debido a la falta de consolidación y de las vinculaciones adecuadas, esta información queda inactiva y, potencialmente, se utiliza poco.

¿Por qué la documentación para el usuario que propusiste es una mejora respecto de la actual? Dado el problema multifacético, el modelo que se propone a continuación elimina los obstáculos relacionados con la navegación, el control de versiones, el seguimiento y la publicación de la documentación, como se detalla a continuación:

El objetivo de la reestructuración de la documentación es simplificar los esfuerzos que realiza un usuario final para navegar. No tiene que seguir un sinfín de vínculos mientras busca información, ya que esta se categorizaría o etiquetaría para simplificar el proceso. Desde una perspectiva administrativa, el control de versiones y el seguimiento sería más fácil, ya que la reestructuración ofrecería la libertad de categorizar en función de las necesidades. La centralización de toda la documentación reestructurada sería para garantizar que el usuario pueda ver toda la información sin tener que consultar varias fuentes.

Análisis: Después de leer el resumen de requisitos y de conversar con el equipo de tutoría, mis deducciones del estado actual de la documentación de Rucio son las siguientes:

Existen seis fuentes principales de documentación: - Vínculo de Google Drive : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7

  • Readthedocs con la tecnología de Sphinx y la fuente en el código Vínculo al código: https://github.com/rucio/rucio Vínculo a ReadtheDocs: https://rucio.readthedocs.io/en/latest/

  • Vínculo de DockerHub: https://hub.docker.com/u/rucio

  • Vínculo de GitHub: https://github.com/rucio/rucio

  • Wikis vínculo: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing

  • Artículos científicos vínculo: https://arxiv.org/abs/1902.09857

La documentación de estas fuentes está en diferentes formatos. Por ejemplo, Google Drive tiene documentación en forma de Presentaciones y Documentos, GitHub tiene archivos principalmente en el lenguaje de marcado reStructuredText, etc. Dado que la falta de control de versiones y seguimiento hace que se publique información redundante en varias fuentes. No hay uniformidad en el etiquetado/categorización de la información. Por lo tanto, se requiere experiencia previa y conocimientos para realizar la búsqueda.

Dada la gran cantidad de formatos y fuentes, se espera reestructurar la información y centralizarla con mkdocs. Para comprender mejor las herramientas, investigué y me familiaricé con su uso.

Veredicto: La documentación existente es no estructurada y está dispersa sin vínculos adecuados. Además, carece de centralización y uniformidad en el formato. Esto hace que los usuarios deban esforzarse más para realizar búsquedas. Estas brechas también generan una presión innecesaria sobre los administradores, los encargados del mantenimiento y los líderes, por lo que se vuelve difícil mantener un enfoque impulsado por la comunidad para el mantenimiento y la actualización de la documentación. La experiencia del usuario y del colaborador se degrada considerablemente y se repetirían

Estructura de la documentación propuesta: Después de un análisis exhaustivo de los requisitos, decidí abordar los principales problemas mediante un modelo de documentación reestructurado.
El modelo reestructurado se demuestra en el prototipo adjunto a continuación y categorizaría cada documento en las siguientes 7 categorías:

  • Acerca de
  • Comenzar
  • Conceptos
  • Interfaces de Rucio
  • Tasks
  • Instructivos
  • Conocimientos avanzados

Por supuesto, hay mejoras, como agregar vínculos, en las que me gustaría trabajar después de completar este programa. Con más de 1,000 usuarios activos que acceden a 500 petabytes de datos en Rucio, la reestructuración propuesta de su documentación debería reducir significativamente la necesidad de que los usuarios recurran a la lista de distribución de asistencia. El objetivo sería mejorar la experiencia del usuario reduciendo la cantidad de porcentajes de clics y mostrando fácilmente la documentación a través de la categorización y el etiquetado. Todo lo que se necesita saber desde la perspectiva del personal de usuarios, operaciones o administradores estaría disponible en 3 clics o menos.

Vínculo de la maqueta: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

Objetivos del proyecto: - Analizar y reducir la información redundante disponible en varias fuentes, es decir, cada dato debe tener una fuente de confianza. - Reestructura etiquetando y categorizando la documentación existente en diferentes partes. - Migra la documentación reestructurada a una vista centralizada basada en mkdocs. - Cambia el formato o importa la documentación que no se puede migrar debido a limitaciones de formato de archivo. - Configura una modificación de la documentación impulsada por la comunidad para garantizar que se cubran los vacíos en términos de vinculaciones, actualizaciones de información o corrección de errores.

Los elementos básicos de este sistema ya están en su lugar. Sin embargo, mi modelo mejoraría el sistema existente, ya que establecería lineamientos adecuados para la contribución y la gobernanza con la documentación adecuada. Además, imagino la incorporación de tableros de proyectos de GitHub para hacer un seguimiento de los problemas y el estado general del proyecto.

Cronograma: - Antes del 16 de agosto --> Familiarizarme con las versiones actuales de la documentación y Rucio --> Aprender nuevas técnicas y habilidades de redacción técnica que serán útiles durante el plazo del proyecto --> Contribuir a los problemas de documentación, si los hay, que se hayan informado en GitHub

  • Vinculación con la comunidad (del 17 de agosto al 13 de septiembre) --> Configura un canal de comunicación y un horario para considerar la diferencia en las zonas horarias (Pune tiene 3 horas y 30 minutos más adelante) --> Principales problemas a identificar para definir mejor los objetivos --> Obtén más información sobre la comunidad, la organización y el marco de trabajo a través de conversaciones. --> Evaluación de la estructura de documentación propuesta con mentores y otros miembros clave de la organización para determinar la viabilidad y factibilidad de la implementación. --> Finalización de las funciones propuestas y cualquier otra modificación que se deba realizar en la documentación existente.

  • Período de documentación (del 14 de septiembre al 30 de noviembre) Según el formato propuesto que formulé aquí, proporcioné un desglose de los principales hitos que planeo alcanzar durante el período de documentación.

--> Logro n° 1: categorización y etiquetado ETC: 28 de septiembre de 2020 Asimilar la documentación disponible y etiquetarla simplificaría en gran medida el proceso de reestructuración y poda.

--> Logro clave n° 2: Análisis, poda y reestructuración FEC: 19 de octubre de 2020 Se analizará la documentación que se categorizó durante el logro clave n° 1 para detectar duplicados y fuentes de información redundantes. Como se indica en la información del proyecto, nos orientamos a una fuente de información para toda la información disponible.

--> Logro n° 3: Centralización y cambio de formato: ETC: 9 de noviembre de 2020 Una vez que la documentación se haya reducido y reestructurado correctamente, mi objetivo sería cambiarle el formato primero. Debido a las diferentes fuentes, los formatos son diferentes y primero deben transformarse en un formato adecuado. Una vez hecho esto, el proceso de centralización sería más fácil.

--> Logro n° 4: Configuración de paneles de seguimiento y documentación sobre la gobernanza o las contribuciones ETC: 23 de noviembre de 2020 Esta fase tiene como objetivo garantizar que, después de completar el proyecto, la documentación siga manteniéndose actualizada. Establecer lineamientos y configurar paneles de proyectos facilitará la tarea de los miembros administrativos de solicitar contribuciones de la comunidad y hacerles un seguimiento de manera eficaz.

--> Evaluación de proyectos (del 30 de noviembre al 5 de diciembre) Enviar un informe de proyecto y la evaluación de mis mentores Escribir y enviar un informe de mi experiencia como participante de la temporada de Documentos.

¿Por qué este proyecto? Creo que complementar el código con documentación bien escrita y con control de versiones es la única forma de permitir una mayor adopción y un mejor uso. En lo personal, me fascina la forma en que el CERN ha sido pionero en la investigación de vanguardia en diferentes áreas de la física. Dada la escala de información procesada, transferida y generada durante esos experimentos, siempre me intrigó cómo se administraban los datos para su uso futuro y de referencia dentro de la organización. Sería un honor contribuir a mejorar la documentación de un framework que ha impulsado investigaciones y descubrimientos científicos increíbles.

¿Por qué soy la persona adecuada para este proyecto? Además de cumplir con los requisitos previos, estoy seguro de que sería la persona adecuada para este proyecto ya que:

Ya estoy trabajando en la modificación de la documentación existente de Kubernetes. Estas contribuciones me permitieron ser reclutado como asistente de documentos de lanzamiento para el ciclo de lanzamiento de Kubernetes 1.19, en el que contribuyo a mantener y actualizar de manera eficaz la documentación de las funciones nuevas que se agregan durante los lanzamientos. Creo que una buena documentación es la base de un producto o servicio excelente. Ya sea procedimental o técnica, la información bien redactada, concisa y de fácil acceso sería un impulso para impulsar la adopción y ayudar a un mejor uso. Como trabajé con sistemas distribuidos basados en datos durante toda mi carrera, creo que estoy en la mejor posición para comprender las complejidades de los requisitos en relación con la documentación de esos sistemas. Como usuario final, conozco las dificultades de la documentación mal escrita o incorrecta y me aseguraré de tenerlas en cuenta durante la reestructuración.