Projet CERN-HSF

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

Résumé du projet

Organisation Open Source:
CERN-HSF
Rédacteur technique:
Ariadne
Nom du projet:
Rucio : modernisation (restructuration et réécriture) de la documentation Rucio
Durée du projet:
Durée standard (trois mois)

Project description

Résumé : Le framework Rucio a été développé dans le but de gérer et d'organiser de grands volumes de données scientifiques distribuées géographiquement dans des centres de données hétérogènes. Doté de fonctionnalités telles que la récupération de données distribuée et la réplication adaptative, le framework est hautement évolutif, modulaire et extensible. Les utilisateurs de ces documents viennent d'horizons divers et ont des besoins variés en matière d'accès. Une bonne documentation pour un tel service doit donc simplifier son adoption et son utilisation par les utilisateurs finaux, tout en servant de référence pour les problèmes courants et le dépannage.

En l'absence de cette documentation, l'utilisation efficace et efficace serait confrontée à d'importants obstacles. Cela peut entraîner une augmentation des coûts d'assistance et présenter un risque de réputation pour l'identité de l'entreprise du produit. La documentation est, après tout, un mode de communication. En veillant à ce que la communication soit encapsulée dans un framework gérable et accessible, tout en restant pertinente avec une gestion des versions appropriée, nous nous assurons de communiquer pour réussir.

Au moment de la rédaction de ce document, le framework Rucio servait à répondre aux exigences énergétiques élevées des expériences ATLAS et CMS au LHC. Il est également utilisé pour répondre aux besoins de diverses communautés scientifiques au-delà du LHC, comme l'astrophysique. Il est donc nécessaire que la documentation soit aussi pertinente et accessible que possible. Grâce à ce projet, le CERN souhaite offrir aux utilisateurs finaux de Rucio une expérience fluide lorsqu'ils utilisent le framework en leur fournissant une vue centralisée pour accéder à toute la documentation pertinente.

État actuel : à ce jour, la documentation utilisateur est répartie sur différents sites et se présente sous plusieurs formats, y compris des articles scientifiques, readthedocs.io avec la source dans le code, Google Drive, GitHub, DockerHub ou des wikis. Les sources multiples entraînent des problèmes de suivi des versions et de validité de la documentation. De plus, un modèle de documentation décentralisé complique considérablement la navigation et l'affichage d'informations pertinentes pour un cas d'utilisation donné. En particulier dans le cas des wikis, les informations fournies pour un test particulier peuvent très bien s'appliquer à d'autres instances situées dans les mêmes sources ou dans d'autres. Cependant, en l'absence de consolidation et de liens appropriés, ces informations restent inactives et, potentiellement, sous-utilisées.

Pourquoi la documentation utilisateur que vous proposez est-elle une amélioration par rapport à la documentation actuelle ? Compte tenu de la complexité du problème, le modèle proposé ci-dessous élimine les obstacles liés à la navigation, à la gestion des versions, au suivi et à la diffusion de la documentation, comme indiqué ci-dessous:

La restructuration de la documentation vise à simplifier la navigation pour l'utilisateur final. Il n'a pas besoin de se perdre dans des recherches sans fin, car les informations sont classées/étiquetées pour plus de simplicité. Du point de vue administratif, la gestion des versions et le suivi seraient facilités, car la restructuration offrirait la possibilité de catégoriser en fonction des exigences. La centralisation de l'ensemble de la documentation restructurée permet de s'assurer que toutes les informations sont visibles par l'utilisateur sans qu'il ait à consulter plusieurs sources.

Analyse : après avoir lu le brief sur les exigences et discuté avec l'équipe de mentorat, voici les conclusions que j'ai tirées sur l'état actuel de la documentation Rucio:

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

  • Readthedocs optimisé 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 provenant de ces sources est disponible dans différents formats. Par exemple, Google Drive propose des documents sous forme de diapositives et de documents, GitHub propose des fichiers principalement au format reStructuredText, etc. Il n'y a pas de gestion des versions ni de suivi, ce qui entraîne la publication d'informations redondantes dans plusieurs sources. Il n'y a pas d'uniformité dans le libellé/la catégorisation des informations. Par conséquent, une expérience et une expertise antérieures sont requises pour effectuer des recherches.

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

Verdict : La documentation existante est non structurée et dispersée, sans liens appropriés. Il manque également de centralisation et d'uniformité dans la mise en forme. Les utilisateurs doivent donc fournir des efforts supplémentaires pour effectuer des recherches. Ces lacunes engendrent également une pression inutile sur les administrateurs, les responsables et les responsables, car il devient difficile de maintenir une approche axée sur la communauté pour la maintenance et la mise à jour de la documentation. L'expérience utilisateur et des contributeurs est considérablement dégradée, et des

Structure de la documentation proposée : après une analyse approfondie des exigences, j'ai décidé de résoudre les principaux problèmes à l'aide d'un modèle de documentation restructuré.
Le modèle restructuré est illustré dans le modèle ci-dessous. Il catégorise chaque élément de documentation dans les sept catégories ci-dessous:

  • À propos
  • Premiers pas
  • Concepts
  • Interfaces Rucio
  • Tâches
  • Tutoriels
  • Savoir-faire avancé

Bien sûr, il y a des améliorations que j'aimerais apporter après la fin de ce programme, comme l'ajout de liens. Avec plus de 1 000 utilisateurs actifs qui accèdent à 500 pétaoctets de données sur Rucio, la restructuration proposée de sa documentation devrait permettre de réduire considérablement le recours à la liste de diffusion d'assistance. L'objectif est d'améliorer l'expérience utilisateur en réduisant le nombre de clics et en affichant facilement la documentation grâce à la catégorisation et au libellé. Tout ce qu'un utilisateur, un opérateur ou un administrateur doit savoir est disponible en trois clics maximum.

Lien vers le modèle: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

Objectifs du projet : - Analyser et élaguer les informations redondantes disponibles à partir de diverses sources. En d'autres termes, chaque information doit avoir une source de vérité unique. - Réorganiser la documentation existante en la catégorisant et en la libellant en différentes parties - Migrer la documentation restructurée vers une vue centralisée basée sur mkdocs - Réorganiser/importer la documentation qui ne peut pas être migrée en raison de contraintes de format de fichier - Configurer la modification de la documentation par la communauté afin de s'assurer que les lacunes sont comblées (en termes de liens, de mises à jour d'informations ou de correction d'erreurs).

Les bases de ce système sont déjà en place. Toutefois, mon modèle améliorerait le système existant en établissant des consignes appropriées pour la contribution et la gouvernance, avec la documentation appropriée. De plus, j'envisage d'intégrer des comités de projet GitHub pour suivre les problèmes et la santé globale du projet.

Calendrier : - Avant le 16 août --> Familiarisez-vous avec les versions actuelles de la documentation et de Rucio --> Apprenez de nouvelles techniques et de nouvelles compétences en écriture technique qui vous seront utiles pendant la durée du projet --> Contribuez à résoudre les problèmes de documentation, le cas échéant, signalés sur GitHub

  • Renforcement des liens au sein de la communauté (17 août-13 septembre) --> Configurer un canal de communication et un horaire en tenant compte de la différence de fuseau horaire (Pune est en avance de trois heures et demie) --> Identifier les principaux problèmes à résoudre pour affiner les objectifs --> En savoir plus sur la communauté, l'organisation et le framework en participant à des conversations. --> Évaluation de la structure de documentation proposée avec des mentors et d'autres membres clés de l'organisation pour évaluer la viabilité et la faisabilité de la mise en œuvre. --> Finalisation des fonctionnalités proposées et de toute autre modification pouvant être apportée à la documentation existante.

  • Période de documentation (14 septembre - 30 novembre) Sur la base du format proposé que j'ai formulé ici, j'ai fourni une répartition des principaux jalons que je prévois d'atteindre pendant la période de documentation.

--> Étape 1: Catégorisation et étiquetage ETC: 28 septembre 2020 Assimiler la documentation disponible et l'étiqueter simplifierait grandement le processus de restructuration et d'élagage.

--> Étape 2: Analyse, élagage et restructuration ETC: 19 octobre 2020 La documentation catégorisée lors de l'étape 1 sera analysée pour détecter les doublons et les sources d'informations redondantes. Comme indiqué dans les informations du projet, nous ciblons une seule source de référence pour toutes les informations disponibles.

--> Étape 3: Centralisation et reformatage : ETC: 9 novembre 2020 Une fois la documentation épurée et restructurée correctement, je vais d'abord essayer 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 cette étape effectuée, le processus de centralisation sera facilité.

--> Étape n° 4: Mise en place de tableaux de suivi et documentation sur la gouvernance et les contributions ETC: 23 novembre 2020 Cette phase vise à s'assurer que la documentation reste à jour après la fin du projet. En définissant des consignes et en configurant des tableaux de projets, les membres de l'équipe administrative pourront plus facilement solliciter les contributions de la communauté et 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 en tant que participant à Season of Docs.

Pourquoi ce projet ? Je pense que compléter le code par une documentation bien rédigée et versionnée est le seul moyen de favoriser l'adoption et une meilleure utilisation. Personnellement, j'ai été fasciné par la façon dont le CERN a été à l'avant-garde 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é intrigué par la façon dont les données étaient gérées à des fins de référence et d'utilisation future au sein de l'entreprise. Ce serait un honneur de contribuer à l'amélioration de la documentation d'un framework qui a permis de réaliser des recherches et des découvertes scientifiques incroyables.

Pourquoi suis-je la personne idéale pour ce projet ? En plus de remplir les conditions préalables, je suis convaincu que je suis la personne idéale pour ce projet, car:

Je travaille déjà à la modification de la documentation existante pour Kubernetes. Grâce à ces contributions, j'ai été recruté en tant qu'ombre de la version Docs pour le cycle de publication de Kubernetes 1.19, dans lequel je contribue à la maintenance et à la mise à niveau efficaces de la documentation sur les nouvelles fonctionnalités ajoutées lors des versions. Je pense qu'une bonne documentation est la base d'un excellent produit/service. Qu'il s'agisse d'informations procédurales ou techniques, des informations bien écrites, concises et facilement accessibles devraient favoriser l'adoption et contribuer à une meilleure utilisation. Ayant travaillé avec des systèmes distribués basés sur les données tout au long de ma carrière, je pense être le mieux placé pour comprendre les subtilités des exigences en ce qui concerne la documentation de ces systèmes. En tant qu'utilisateur final, je connais les écueils d'une documentation mal rédigée ou incorrecte, et je veillerai à en tenir compte lors de la restructuration.