Proyecto CERN-HSF

Esta página contiene 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

Escritor técnico:

Ariadna

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 marco de trabajo 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 es altamente escalable, modular y extensible, por lo que ofrece funciones como la recuperación de datos distribuidos y la replicación adaptable. Los consumidores de documentación de este tipo de servicio provendrán de diversos orígenes y tendrán distintos requisitos cuando accedan a él. Por lo tanto, una buena documentación de este tipo de servicio debería simplificar su adopción y utilización para los usuarios finales, a la vez que también debe ser una referencia para los problemas comunes y la solución de problemas.

Si no existiera dicha documentación, el uso eficiente y eficaz tendrían muchos obstáculos. Esto podría generar un aumento en los costos de asistencia y representar un riesgo para la reputación de 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 manejable y accesible, y que siga siendo relevante con un control de versiones adecuado, es garantizar la comunicación para el éxito.

Al momento de la redacción de este documento, se utilizó el marco de trabajo Rucio para satisfacer los requisitos de alta energía de los experimentos de ATLAS y CMS en el GCH. También se utiliza para satisfacer las necesidades de diversas comunidades científicas más allá del GHC, como la astrofísica, por lo que la documentación debe ser 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 utilizan el marco de trabajo proporcionando una vista centralizada para acceder a toda la documentación relevante.

Estado actual: A partir de hoy, la documentación del usuario se distribuye en diferentes lugares y se encuentra en múltiples formatos, incluidos artículos científicos, readthedocs.io con el código fuente en el código, Google Drive, GitHub, DockerHub o Wikis. Múltiples fuentes presentan problemas con el seguimiento de versiones y la precisión de la documentación. Además, un modelo descentralizado de documentación supone muchos obstáculos para la navegación y la aparición de información relevante para un caso de uso determinado. Especialmente en el caso de los Wikis, la información proporcionada para un experimento particular podría aplicarse muy bien a otras instancias que residen en la misma fuente u otras fuentes también. Sin embargo, debido a la falta de consolidación y las vinculaciones adecuadas, esta información permanece latente y, potencialmente, no se utiliza lo suficiente.

¿Por qué la documentación de usuario propuesta es una mejora con respecto a la actual? Dado el problema multifacético, el modelo propuesto a continuación elimina los obstáculos de la navegación, el control de versiones, el seguimiento y la aparición de documentos, tal como se detalla a continuación:

La reestructuración de la documentación tiene como objetivo simplificar los esfuerzos destinados a navegar para un usuario final. No necesita caer en madrigueras mientras busca información, ya que se categorizarían o etiquetan para simplificar el proceso. Desde una perspectiva administrativa, el control de versiones y el seguimiento serían más sencillos, ya que la reestructuración ofrecería la libertad de categorizar según los requisitos. Centralizar toda la documentación reestructurada sería garantizar que toda la información sea visible para el usuario sin tener que consultar varias fuentes.

Análisis: Después de leer el resumen de requisitos y tener conversaciones con el equipo de mentores, mi deducción de la documentación del estado actual de Rucio será la siguiente:

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

• Lee los documentos con la tecnología de Sphinx y que incluyen 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/

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

• GitHub Vínculo: 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 formato de Presentaciones y Documentos, GitHub tiene archivos principalmente en el lenguaje de marcado reStructuredText, etc. Hay una falta de control de versiones y seguimiento, lo que provoca que se publique información redundante en múltiples fuentes. No hay uniformidad en el etiquetado y la categorización de la información. Por lo tanto, se requiere experiencia previa para la búsqueda.

Con la infinidad de formatos y fuentes disponibles, se espera reestructurar la información y centralizarla mediante mkdocs. Para comprender mejor las herramientas, investigué y me familiaricé con su uso.

Veredicto: La documentación existente no está estructurada y está dispersa sin la vinculación adecuada. Además, carece de centralización y uniformidad de formato. Como resultado, los usuarios tienen que esforzarse más para realizar búsquedas. Estas brechas también generan una presión innecesaria sobre los administradores, encargados del mantenimiento o 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 de los usuarios y colaboradores se ve afectada considerablemente y se podrían repetir

Estructura de la documentación propuesta: Después de un análisis exhaustivo de los requisitos, decidí abordar los principales puntos débiles a través de un modelo de documentación reestructurado.
El modelo reestructurado se demuestra en la maqueta adjunta a continuación y cada documento podría clasificarse en las siguientes 7 categorías:

• Acerca de
• Getting Started
• Conceptos
• Rucio Interfaces
• Tasks
• Instructivos
• Conocimientos avanzados

Por supuesto, también se implementaron mejoras, como agregar vínculos en los que me gustaría trabajar luego de finalizar 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 mediante la disminución de la cantidad de tasas de clics y la simple presentación de la documentación mediante la categorización y el etiquetado. Todo lo que hay que saber desde la perspectiva del usuario, las operaciones y el personal administrativo estaría disponible con 3 clics o menos.

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

Objetivos del proyecto: - Analizar y eliminar la información redundante disponible de diversas fuentes; es decir, cada dato debe tener una fuente de verdad. - Para reestructurar, etiqueta y categorizar la documentación existente en diferentes partes. - Migra la documentación reestructurada a una vista centralizada basada en archivos de marketing. - Vuelve a formatear e importa la documentación que no se puede migrar debido a restricciones de formato de archivo. - Configura la modificación de la documentación impulsada por la comunidad para asegurarte de que falte información para garantizar que se llenen los vacíos faltantes, en términos de vinculaciones, actualizaciones de información o corrección de errores.

Las condiciones básicas de este sistema ya existen; sin embargo, mi modelo mejoraría el sistema existente estableciendo pautas adecuadas para la contribución y la administración con la documentación adecuada. Además, preveo incorporar tableros de proyecto de GitHub para hacer un seguimiento de los problemas y el estado de salud general del proyecto.

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

• Vínculos con la comunidad (del 17 de agosto al 13 de septiembre) --> Configure un canal de comunicación y un horario para considerar la diferencia en las zonas horarias (pune 3 horas con 30 minutos de anticipación) --> Principales dificultades que se deben identificar para perfeccionar los objetivos --> Participa en conversaciones para obtener más información sobre la comunidad, la organización y el marco de trabajo. --> Evaluación de la estructura de documentación propuesta con mentores y otros miembros clave de la organización para verificar la viabilidad y la viabilidad de la implementación. --> Finalización de las funciones propuestas y cualquier otra modificación que sea necesario 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í, he proporcionado un desglose de los principales hitos que planeo alcanzar durante el período de documentación.

--> Logro 1: Categorización y etiquetado ETC: 28 de septiembre de 2020 Asimilar la documentación disponible y etiquetarla simplificaría enormemente el proceso de reestructuración y reducción.

--> Logro 2: Análisis, reducción y reestructuración ETC: 19 de octubre de 2020 La documentación que se categorizó durante la meta n.o 1 se analizará en busca de duplicados y fuentes de información redundantes. Como se indica en la información del proyecto, nuestro objetivo es una única fuente fiable para toda la información disponible.

--> Logro n.o 3: Centralización y reformateo: ETC: 9 de noviembre de 2020 Una vez que la documentación se haya reducido y reestructurado correctamente, debería cambiar su formato primero. Debido a las diversas fuentes, los formatos son diferentes y primero hay que transformarlos en un formato adecuado. Una vez hecho esto, el proceso de centralización sería más fácil.

--> Logro 4: Configurar placas de seguimiento y documentación sobre la administración o las contribuciones ETC: 23 de noviembre de 2020 Esta fase tiene como objetivo garantizar que, una vez finalizado el proyecto, la documentación se mantenga actualizada. Establecer pautas y crear juntas de proyectos aliviará la carga de los miembros administrativos en solicitar contribuciones de la comunidad y realizar un seguimiento de ellas de manera efectiva.

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

¿Por qué este proyecto? Creí que complementar el código con documentación bien escrita y controlada por versiones es la única manera 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 investigaciones de vanguardia en diferentes áreas de la física. Dada la escala de información procesada, transferida y generada durante esos experimentos, siempre me intrigaba cómo se administraban los datos para referencia y uso futuro dentro de la organización. Sería un honor contribuir a la mejora de la documentación para un marco que ha sido el impulsor de algunas investigaciones y descubrimientos científicos asombrosos.

¿Por qué soy la persona indicada para este proyecto? Además de cumplir con los requisitos previos, confío en que seré la persona indicada para este proyecto, ya que:

Ya estoy trabajando para modificar la documentación existente de Kubernetes. Gracias a estas contribuciones, me reclutaron como Sombra de Documentos de Versión para el ciclo de lanzamiento de Kubernetes 1.19, en el que contribuyo a mantener y actualizar de forma eficaz la documentación de las funciones nuevas que se agregan durante los lanzamientos. Creo que una buena documentación es la columna vertebral de un gran producto o servicio. Ya sea de procedimiento o técnica, la información bien redactada, concisa y de fácil acceso sería un impulso para impulsar la adopción y facilitar un mejor uso. Después de haber trabajado con sistemas distribuidos basados en datos a lo largo de mi carrera, creo que estoy mejor posicionada para comprender las complejidades de los requisitos con respecto a la documentación de esos sistemas. Como soy usuario final, estoy familiarizado con las dificultades de la documentación mal escrita o incorrecta, y me aseguraré de incluirlas en la reestructuración.