CERN-HSF-Projekt

Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.

Projektzusammenfassung

Open-Source-Organisation:
CERN-HSF
Technischer Redakteur:
Ariadne
Projektname:
Rucio – Die Rucio-Dokumentation modernisieren (umstrukturieren und umschreiben)
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

Zusammenfassung: Das Rucio-Framework wurde mit dem Ziel entwickelt, große Mengen an geografisch verteilten wissenschaftlichen Daten über heterogene Rechenzentren hinweg zu verwalten und zu organisieren. Das Framework bietet Funktionen wie verteilte Datenwiederherstellung und adaptive Replikation und ist äußerst skalierbar, modular und erweiterbar. Die Nutzer der Dokumentation für einen solchen Dienst haben unterschiedliche Hintergründe und Anforderungen beim Zugriff darauf. Eine gute Dokumentation für einen solchen Dienst sollte daher die Einführung und Nutzung für die Endnutzer vereinfachen und gleichzeitig als Referenz für häufige Probleme und zur Fehlerbehebung dienen.

Ohne eine solche Dokumentation gäbe es erhebliche Hürden bei einer effizienten und effektiven Auslastung. Dies könnte zu höheren Supportkosten führen und ein Risiko für den Ruf der Unternehmensidentität des Produkts darstellen. Dokumentation ist schließlich eine Art der Kommunikation. Daher ist es wichtig, sicherzustellen, dass die Kommunikation in einem überschaubaren und zugänglichen Framework gekapselt ist und gleichzeitig mit einer geeigneten Versionsverwaltung relevant bleibt, um so für eine erfolgreiche Kommunikation zu sorgen.

Zum Zeitpunkt der Entstehung dieses Artikels wurde das Rucio-Framework für den Energiebedarf der ATLAS- und CMS-Experimente am LHC verwendet. Sie wird auch eingesetzt, um die Bedürfnisse unterschiedlicher wissenschaftlicher Gemeinschaften außerhalb des LHC, etwa der Astrophysik, zu unterstützen. Dadurch wird es notwendig, dass die Dokumentation so relevant und zugänglich wie möglich ist. Mit diesem Projekt möchte das CERN den Endnutzern von Rucio eine nahtlose Nutzung des Frameworks ermöglichen, indem eine zentrale Ansicht für den Zugriff auf alle relevante Dokumentation bereitgestellt wird.

Aktueller Status: Mittlerweile ist die Nutzerdokumentation auf verschiedene Orte verteilt und in verschiedenen Formaten verfügbar, darunter wissenschaftliche Artikel, readthedocs.io mit Quellcode im Code, Google Drive, GitHub, DockerHub oder Wikis. Mehrere Quellen führen zu Problemen bei der Nachverfolgung von Versionen und der Richtigkeit der Dokumentation. Darüber hinaus stellt ein dezentralisiertes Dokumentationsmodell erhebliche Hürden bei der Navigation und der Bereitstellung relevanter Informationen für einen bestimmten Anwendungsfall dar. Insbesondere im Fall von Wikis können die für ein bestimmtes Experiment bereitgestellten Informationen durchaus auch auf andere Instanzen anwendbar sein, die in derselben oder einer anderen Quelle enthalten sind. Aufgrund mangelnder Konsolidierung und angemessener Verknüpfungen sind diese Informationen jedoch ruhen und möglicherweise nicht ausreichend genutzt.

Warum ist Ihre vorgeschlagene Nutzerdokumentation eine Verbesserung gegenüber der aktuellen? Angesichts des vielschichtigen Problems beseitigt das unten vorgeschlagene Modell die Hürden bei der Navigation, der Versionsverwaltung, dem Tracking und der Bereitstellung der Dokumentation, wie unten beschrieben:

Die Neustrukturierung der Dokumentation zielt darauf ab, die Navigation für Endnutzer zu vereinfachen. Er/sie muss bei der Suche nach Informationen nicht in Kaninchenlöchern suchen, da diese der Einfachheit halber kategorisiert werden würden. Aus administrativer Sicht wäre Versionsverwaltung und Nachverfolgung einfach, da eine Restrukturierung die Möglichkeit hätte, auf der Grundlage der Anforderungen zu kategorisieren. Die Zentralisierung der gesamten neu strukturierten Dokumentation besteht darin, sicherzustellen, dass alle Informationen für die Nutzer sichtbar sind, ohne auf mehrere Quellen verweisen zu müssen.

Analyse: Nach dem Durchlesen der Anforderungsübersicht und Gesprächen mit dem Mentoring-Team fallen meine Abzüge vom aktuellen Stand der Rucio-Dokumentation wie folgt aus:

Es gibt sechs Hauptquellen für die Dokumentation: – Link zu Google Drive : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7

  • Readthedocs powered by Sphinx mit Quellcode im Code Link zum Code: https://github.com/rucio/rucio Link zu ReadtheDocs: https://rucio.readthedocs.io/en/latest/

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

  • GitHub-Link: https://github.com/rucio/rucio

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

  • Wissenschaftliche Artikel Link: https://arxiv.org/abs/1902.09857

Die Dokumentation dieser Quellen liegt in unterschiedlichen Formaten vor. So gibt es z. B. in Google Drive Dokumentationen in Form von Präsentationen und Docs, auf GitHub sind Dateien hauptsächlich in der Auszeichnungssprache reStructuredText usw. verfügbar. Es fehlt an Versionsverwaltung und Tracking, was dazu führt, dass redundante Informationen in mehreren Quellen veröffentlicht werden. Es gibt keine Einheitlichkeit bei der Beschriftung/Kategorisierung von Informationen. Daher sind Vorkenntnisse und Fachwissen für die Suche erforderlich.

Angesichts der Vielzahl von Formaten und Quellen wird erwartet, die Informationen neu zu strukturieren und mithilfe von mkdocs zu zentralisieren. Um mir ein besseres Verständnis der Tools zu verschaffen, habe ich mich mit ihrer Verwendung informiert.

Ergebnis: Die vorhandene Dokumentation ist unstrukturiert und ohne entsprechende Verknüpfung verstreut. Außerdem fehlt es an Zentralisierung und Einheitlichkeit bei der Formatierung. Dies führt dazu, dass Nutzer zusätzlichen Aufwand bei der Suche aufwenden müssen. Derartige Lücken bringen außerdem unnötigen Druck auf die Administratoren/Betreuer/Leads, weshalb es schwierig wird, einen von der Community ausgerichteten Ansatz für die Wartung und Aktualisierung der Dokumentation aufrechtzuerhalten. Die Nutzung für Nutzer und Beitragende ist erheblich beeinträchtigt und es käme wiederholt zu

Struktur der vorgeschlagenen Dokumentation: Nach gründlicher Analyse der Anforderungen habe ich beschlossen, die wichtigsten Probleme mithilfe eines neu strukturierten Dokumentationsmodells zu beheben.
Das neu strukturierte Modell wird im unten angehängten Modell demonstriert und würde jede Dokumentation in die folgenden sieben Kategorien einordnen:

  • Info
  • Erste Schritte
  • Konzepte
  • Rucio-Benutzeroberflächen
  • Aufgaben
  • Tutorials
  • Erweitertes Know-how

Natürlich gibt es noch Verbesserungen, wie das Hinzufügen von Links, an denen ich nach Abschluss dieses Programms gerne arbeiten würde. Da über 1.000 aktive Nutzer auf 500 Petabyte an Daten auf Rucio zugreifen, sollte die vorgeschlagene Umstrukturierung der Dokumentation in der Lage sein, die Notwendigkeit von Nutzern, die Support-Mailingliste aufzurufen, erheblich reduzieren. Ziel ist es, die Nutzererfahrung zu verbessern, indem die Anzahl der Klickraten gesenkt und die Dokumentation durch Kategorisierung und Labeling leicht zugänglich gemacht werden kann. Alles, was aus der Perspektive von Benutzer/Betrieb/Administrator zu wissen ist, ist mit höchstens drei Klicks verfügbar.

Modell-Link: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

Projektziele: - Analysieren und entfernen Sie redundante Informationen aus verschiedenen Quellen, d. h., jede Information sollte eine zentrale Informationsquelle haben. - Neustrukturierung durch Hinzufügen von Labels und Kategorisieren der vorhandenen Dokumentation in verschiedene Teile - Migration der umstrukturierten Dokumentation zu einer zentralen Ansicht basierend auf mkdocs - Umformatierung/Import der Dokumentation, die aufgrund von Einschränkungen des Dateiformats nicht migriert werden kann - Community-gesteuerte Änderung der Dokumentation einrichten, um sicherzustellen, dass fehlende Lücken geschlossen werden - in Bezug auf Verknüpfungen, Aktualisierungen von Informationen oder Korrektur von Fehlern.

Die Grundzüge für dieses System sind bereits vorhanden. Mein Modell würde jedoch das bestehende System verbessern, indem es geeignete Richtlinien für Beitrag und Governance mit entsprechender Dokumentation festlegen würde. Außerdem überlege ich, wie man GitHub-Projekt-Boards einbindet, um Probleme und den Gesamtzustand des Projekts zu verfolgen.

Zeitplan: - Vor dem 16. August --> Aktuelle Versionen der Dokumentation und Rucio kennenlernen --> Neue Techniken und technische Fähigkeiten erlernen, die während der Projektlaufzeit hilfreich sein werden --> Einen Beitrag zu Dokumentationsproblemen leisten, die auf GitHub gemeldet werden

  • Community-Bonding (17. August bis 13. September) --> Richten Sie einen Kommunikationskanal und eine Zeit ein, um den Unterschied zwischen den Zeitzonen zu berücksichtigen (Pune liegt 3 Stunden, 30 Minuten voraus) --> Wichtige Probleme, die zur Verfeinerung der Ziele zu identifizieren sind --> Erfahren Sie mehr über die Community, die Organisation und das Framework, indem Sie sich an Gesprächen beteiligen. --> Prüfung der vorgeschlagenen Dokumentationsstruktur mit Mentoren und anderen wichtigen Mitgliedern der Organisation auf Umsetzbarkeit und Durchführbarkeit der Umsetzung. --> Endgültigkeit der vorgeschlagenen Funktionen und aller anderen Änderungen, die möglicherweise an der vorhandenen Dokumentation vorgenommen werden müssen.

  • Dokumentationszeitraum (14. September bis 30. November) Auf Grundlage des hier vorgeschlagenen Formats habe ich eine Aufschlüsselung der wichtigsten Meilensteine bereitgestellt, die ich während des Dokumentationszeitraums erreichen möchte.

--> Meilenstein Nr. 1: Kategorisierung und Labelling ETC: 28. September 2020 Die Anpassung der verfügbaren Dokumentation und der Beschriftung würde den Restrukturierungs- und Bereinigungsprozess erheblich vereinfachen.

--> Meilenstein 2: Analyse, Kürzung und Umstrukturierung ETC: 19. Oktober 2020 Dokumentation, die während des 1. Meilensteins kategorisiert wurde, wird auf Duplikate und redundante Informationsquellen analysiert. Wie in den Projektinformationen angegeben, greifen wir für alle verfügbaren Informationen auf eine einzige Datenquelle zurück.

--> Meilenstein Nr. 3: Zentralisierung und Neuformatierung: ETC: 9. November 2020 Sobald die Dokumentation gekürzt und richtig umstrukturiert wurde, versuche ich, sie zuerst neu zu formatieren. Aufgrund der verschiedenen Quellen unterscheiden sich die Formate und müssen zuerst in ein geeignetes Format umgewandelt werden. Dadurch wird der Zentralisierungsprozess vereinfacht.

--> 4. Meilenstein: Tracking-Boards einrichten und Dokumentation zu Governance/Beiträgen (ETC): 23. November 2020 In dieser Phase wird sichergestellt, dass die Dokumentation nach Abschluss des Projekts weiterhin auf dem neuesten Stand ist. Die Festlegung von Richtlinien und die Einrichtung von Projektausschüssen erleichtern den Verwaltungsmitgliedern die Aufgabe, Beiträge aus der Gemeinschaft einzuholen und diese effektiv zu verfolgen.

--> Projektbewertung (30. November bis 5. Dezember) Projektbericht und Bewertung meiner Mentoren einreichen Verfasse einen Bericht über meine Erfahrungen als Teilnehmer an „Season of Docs“ und übermittle ihn.

Warum dieses Projekt? Ich bin der Meinung, dass es die einzige Möglichkeit ist, den Code durch eine gut verfasste und versionierte Dokumentation zu ergänzen, um eine weitere Akzeptanz und eine bessere Nutzung zu ermöglichen. Ich persönlich war fasziniert davon, wie das CERN wegweisende Forschung in verschiedenen Bereichen der Physik war. Angesichts des Umfangs der bei solchen Experimenten verarbeiteten, übertragenen und generierten Informationen war ich immer fasziniert davon, wie Daten für Referenzzwecke und zukünftige Verwendung innerhalb des Unternehmens verwaltet werden. Es wäre eine Ehre, einen Beitrag zur Verbesserung der Dokumentation für ein Framework zu leisten, das einige erstaunliche wissenschaftliche Forschungen und Entdeckungen unterstützt hat.

Warum bin ich die richtige Person für dieses Projekt? Ich bin zuversichtlich, dass ich nicht nur die Voraussetzungen für dieses Projekt erfülle, sondern auch die richtige Person bin, da:

Ich arbeite bereits daran, die vorhandene Dokumentation für Kubernetes zu ändern. Aufgrund dieser Beiträge wurde ich als Release-Dokumentationsschatten für den Kubernetes-Release-Zyklus 1.19 ausgewählt. Dabei trage ich zur effektiven Verwaltung und zum Upgrade der Dokumentation für neue Funktionen bei, die während der Releases hinzugefügt werden. Ich bin der Meinung, dass eine gute Dokumentation die Basis für ein großartiges Produkt/eine gute Dienstleistung ist. Ob verfahrenstechnisch oder technisch – gut formulierte, prägnante und leicht zugängliche Informationen sind ein Anstoß für die Akzeptanz und eine bessere Nutzung. Ich habe im Laufe meiner Karriere schon immer mit datengesteuerten verteilten Systemen gearbeitet und ich glaube, dass ich am besten in der Lage bin, die komplexen Anforderungen in Bezug auf die Dokumentation für solche Systeme zu verstehen. Da ich selbst Endnutzer bin, bin ich mit den Fallstricken schlecht geschriebener/falscher Dokumentationen vertraut und würde diese bei der Neustrukturierung berücksichtigen.