Projet CERN-HSF

Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.

Résumé du projet

Organisation Open Source:
CERN-HSF
Rédacteur technique:
Ariadne
Nom du projet:
Rucio – Moderniser (restructurer et réécrire) la documentation Rucio
Durée du projet:
Durée standard (3 mois)

Project description

Résumé : Le framework Rucio a été développé dans le but de gérer et d'organiser d'importants volumes de données scientifiques distribuées géographiquement dans des centres de données hétérogènes. Offrant des fonctionnalités telles que la récupération de données distribuée et la réplication adaptative, ce framework est hautement évolutif, modulaire et extensible. Les consommateurs de la documentation d'un tel service proviennent d'horizons variés et ont des exigences variées pour y accéder. Une bonne documentation sur ce type de service doit donc simplifier son adoption et son utilisation pour les utilisateurs finaux, tout en servant de référence pour les problèmes courants et les dépannages.

Sans ces documents, une utilisation efficace de la solution se traduira par des obstacles considérables. Cela peut entraîner une augmentation des coûts d'assistance et nuire à la réputation du produit. La documentation est, après tout, un mode de communication. En vous assurant que la communication est encapsulée dans un framework gérable et accessible, tout en restant pertinente avec une gestion des versions appropriée, vous nous assurez que nous communiquons pour réussir.

Au moment où nous écrivons ces lignes, la structure Rucio servait à répondre aux besoins en énergie des expériences ATLAS et CMS au LHC. Il sert également à répondre aux besoins de diverses communautés scientifiques au-delà du LHC, comme l'astrophysique, ce qui rend la documentation aussi pertinente et accessible que possible. Avec l'aide de ce projet, le CERN souhaite permettre aux utilisateurs finaux de Rucio de bénéficier d'une expérience fluide tout en utilisant le framework en leur offrant une vue centralisée pour accéder à toute la documentation pertinente.

État actuel : À l'heure actuelle, la documentation utilisateur est disséminée à différents endroits et dans plusieurs formats, y compris des articles scientifiques, readthedocs.io avec la source dans le code, Google Drive, GitHub, DockerHub ou Wikis. Plusieurs sources engendrent des problèmes avec le suivi des versions et l'exactitude de la documentation. De plus, un modèle décentralisé de documentation pose des problèmes importants en termes de navigation et d'affichage d'informations pertinentes pour un cas d'utilisation donné. Dans le cas des wikis, les informations fournies pour une expérience particulière peuvent très bien s'appliquer à d'autres instances résidant dans la même source ou dans d'autres. Toutefois, en l'absence de consolidation et de liens appropriés, ces informations sont inactives et, potentiellement sous-utilisées.

Pourquoi la documentation utilisateur proposée est-elle une amélioration par rapport à la documentation actuelle ? Compte tenu de ces multiples facettes, le modèle proposé ci-dessous élimine les obstacles liés à la navigation, à la gestion des versions, au suivi et à l'affichage de la documentation, comme indiqué ci-dessous:

La restructuration de la documentation vise à simplifier les efforts de navigation pour un utilisateur final. Il n'est pas nécessaire qu'il recherche des informations dans les cases du lapin, car ces contenus seraient classés/libellés par souci de simplicité. D'un point de vue administratif, la gestion des versions et le suivi seraient facilités, car la restructuration offrirait la liberté de catégoriser en fonction des exigences. Centraliser toute la documentation restructurée serait de s'assurer que toutes les informations sont visibles par l'utilisateur sans avoir à se référer à plusieurs sources.

Analyse : Après avoir lu la synthèse des conditions requises et avoir discuté avec l'équipe de mentorat, mes déductions sur l'état actuel de la documentation Rucio sont les suivantes:

Il existe six principales sources de documentation : - Lien Google Drive : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7

  • Readthedocs fourni par Sphinx avec la source dans le code Lien vers le code: https://github.com/rucio/rucio Lien vers ReadtheDocs: https://rucio.readthedocs.io/en/latest/

  • Lien DockerHub: https://hub.docker.com/u/rucio

  • Lien GitHub: https://github.com/rucio/rucio

  • Wikis Lien: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing

  • Articles scientifiques Lien: https://arxiv.org/abs/1902.09857

La documentation de ces sources se présente dans différents formats. Par exemple, Google Drive dispose de documents sous forme de documents Slides et Docs, GitHub dispose de fichiers principalement en langage de balisage reStructuredText, etc. L'absence de gestion des versions et de suivi entraîne la publication d'informations redondantes dans plusieurs sources. L'étiquetage/la catégorisation des informations n'est pas uniforme. Par conséquent, une expérience et une expertise antérieures sont nécessaires pour effectuer des recherches.

Compte tenu de la multitude de formats et de sources, l'objectif est de restructurer les informations et de les centraliser à l'aide de mkdocs. Afin de mieux comprendre ces outils, j'ai fait des recherches et me suis familiarisé avec leur utilisation.

Verdict : La documentation existante n'est pas structurée et dispersée sans liens appropriés. Il manque également de centralisation et d'uniformité de la mise en forme. Les utilisateurs doivent donc déployer des efforts supplémentaires pour effectuer des recherches. De telles lacunes engendrent également une pression inutile sur les administrateurs, les responsables ou les responsables. Il est donc difficile de maintenir une approche communautaire pour la maintenance et la mise à jour de la documentation. L'expérience utilisateur/contributeur est considérablement dégradée, et vous risquez d'être répété

Structure de la documentation proposée : Après une analyse approfondie des exigences, j'ai décidé de traiter les principales difficultés rencontrées via un modèle de documentation restructuré.
Le modèle restructuré est présenté dans la maquette ci-dessous et classe chaque document dans les sept catégories ci-dessous:

  • À propos
  • Getting Started
  • Concepts
  • Interfaces Rucio
  • Tâches
  • Tutoriels
  • Un savoir-faire avancé

Bien sûr, il y a des améliorations comme l’ajout de liens sur lesquels j’aimerais travailler après avoir terminé ce programme. Avec plus de 1 000 utilisateurs actifs accédant à 500 pétaoctets de données sur Rucio, la restructuration proposée de sa documentation devrait permettre de réduire considérablement la nécessité pour les utilisateurs d'avoir recours à la liste de diffusion d'assistance. L'objectif est d'améliorer l'expérience utilisateur en diminuant le nombre de taux de clics et en facilitant l'affichage de la documentation via la catégorisation et l'étiquetage. Tout ce qu'il y a à savoir du point de vue des utilisateurs, des opérations ou du personnel administratif est disponible en trois clics maximum.

Lien de simulation: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

Objectifs du projet : - Analyser et élaguer les informations redondantes disponibles depuis différentes sources. autrement dit, chaque information doit avoir une source unique. - Restructurez la documentation existante en la classant et en la classant en différentes parties - Migrez la documentation restructurée vers une vue centralisée basée sur des fichiers mkdocs - Reformatez/importez la documentation qui ne peut pas être migrée en raison des contraintes de format de fichier - Configurez des modifications de la documentation par la communauté pour vous assurer que les lacunes sont comblées (en termes d'associations, de mises à jour d'informations ou de correction d'erreurs).

Les bases de ce système sont déjà en place, mais mon modèle améliorerait le système existant en établissant des directives appropriées pour la contribution et la gouvernance avec une documentation appropriée. Par ailleurs, j'envisage d'intégrer des tableaux de bord de projet GitHub pour suivre les problèmes et la santé globale du projet.

Calendrier : - Avant le 16 août --> Me familiariser avec les versions actuelles de la documentation et de Rucio --> Apprendre de nouvelles techniques et compétences de rédaction technique qui seront utiles pendant la durée du projet --> Participer aux problèmes de documentation signalés sur GitHub, le cas échéant

  • Engagement avec la communauté (du 17 août au 13 septembre) --> Définissez un canal de communication et un horaire pour tenir compte du décalage horaire (Pune est dans 3 heures et 30 minutes d'avance) --> Principaux difficultés à identifier afin d'affiner les objectifs --> Apprenez-en davantage sur la communauté, l'organisation et le cadre en discutant. --> Évaluation de la structure de documentation proposée avec des mentors et d'autres membres clés de l'organisation pour déterminer la viabilité et la faisabilité de la mise en œuvre. --> Finalisation des fonctionnalités proposées et toute autre modification nécessaire à la documentation existante.

  • Période de documentation (14 septembre - 30 novembre) Basé sur le format proposé ici, j'ai fourni une répartition des principaux jalons que je prévois d'atteindre au cours de la période de documentation.

--> Jalon 1: Catégorisation et étiquetage ETC: 28 septembre 2020 Associer la documentation disponible et les étiqueter simplifierait considérablement le processus de restructuration et d'élagage.

--> Étape 2: Analyse, élagage et restructuration ETC: 19 octobre 2020 Les documents classés lors de l'étape 1 seront analysés afin de détecter les doublons et les sources d'informations redondantes. Comme indiqué dans les informations du projet, nous ciblons une source d'informations unique pour toutes les informations disponibles.

--> Étape 3: Centralisation et reformatage : ETC: 9 novembre 2020 Une fois que la documentation a été nettoyée et restructurée correctement, j'essaie d'abord de la reformater. En raison des différentes sources, les formats sont différents et doivent d'abord être transformés en un format approprié. Une fois cela fait, le processus de centralisation sera simplifié.

--> Étape 4: Mise en place de tableaux de suivi et documentation sur la gouvernance/les contributions ETC: 23 novembre 2020 Cette phase permet de s'assurer que la documentation reste à jour une fois le projet terminé. La mise en place de directives et la mise en place de conseils de projet allègeront le fardeau des membres administratifs de solliciter des contributions de la communauté et de les suivre efficacement.

--> Évaluation du projet (30 novembre - 5 décembre) Envoyer un rapport de projet et une évaluation de mes mentors Rédiger et envoyer un rapport sur mon expérience de participant à Season of Docs

Pourquoi ce projet ? Je pense que l'ajout d'une documentation bien rédigée et versionnée au code était le seul moyen de favoriser l'adoption et une meilleure utilisation. Personnellement, j'ai été fasciné par la façon dont le CERN est un pionnier de la recherche de pointe dans différents domaines de la physique. Compte tenu de l'ampleur des informations traitées, transférées et générées lors de ces tests, j'ai toujours été intéressé par la façon dont les données étaient gérées à des fins de référence et d'utilisation future dans l'organisation. Ce serait un honneur de contribuer à l'amélioration de la documentation d'un cadre qui a conduit d'incroyables recherches et découvertes scientifiques.

Pourquoi suis-je la personne responsable de ce projet ? En plus de remplir les prérequis, je suis convaincu d'être la bonne personne pour ce projet puisque:

Je travaille déjà à modifier la documentation existante de Kubernetes. Ces contributions m'ont permis d'être désigné comme testeur des documents de publication pour le cycle de publication de Kubernetes 1.19, dans lequel je contribue efficacement à la maintenance et à la mise à niveau de la documentation sur les nouvelles fonctionnalités ajoutées lors des versions. Pour proposer un produit ou un service de qualité, il est essentiel d'avoir une documentation de qualité. Qu'elles soient procédurales ou techniques, des informations bien rédigées, concises et facilement accessibles pourraient inciter à l'adoption et à une meilleure utilisation. Après avoir travaillé avec des systèmes distribués basés sur les données tout au long de ma carrière, je pense que je suis le mieux placé pour comprendre les subtilités des exigences en matière de documentation pour ces systèmes. Ayant été moi-même un utilisateur final, je suis familiarisé avec les pièges d'une documentation mal écrite/incorrecte et je prendrai en compte ces éléments lors de la restructuration.