CERN-HSF-Projekt

Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:
CERN-HSF
Technischer Redakteur:
Ariadne
Projektname:
Rucio – Rucio-Dokumentation modernisieren (neu strukturieren und umschreiben)
Projektdauer:
Standardlänge (3 Monate)

Projektbeschreibung

Zusammenfassung: Das Rucio-Framework wurde entwickelt, um große Mengen geografisch verteilter wissenschaftlicher Daten in heterogenen Rechenzentren zu verwalten und zu organisieren. Das Framework bietet Funktionen wie die verteilte Datenwiederherstellung und adaptive Replikation und ist hoch skalierbar, modular und erweiterbar. Die Nutzer der Dokumentation für einen solchen Dienst haben unterschiedliche Hintergründe und unterschiedliche Anforderungen beim Zugriff darauf. Eine gute Dokumentation für einen solchen Dienst sollte daher die Einführung und Nutzung für Endnutzer vereinfachen und gleichzeitig als Referenz für häufige Probleme und Fehlerbehebung dienen.

Ohne eine solche Dokumentation würde die effiziente und effektive Nutzung erheblich erschwert. Dies kann zu höheren Supportkosten führen und ein Reputationsrisiko für die Unternehmensidentität des Produkts darstellen. Dokumentation ist schließlich eine Form der Kommunikation. Wenn wir dafür sorgen, dass die Kommunikation in einem überschaubaren und zugänglichen Rahmen eingebettet ist und gleichzeitig mit einer geeigneten Versionierung relevant bleibt, sorgen wir so für eine erfolgreiche Kommunikation.

Zum Zeitpunkt der Erstellung dieses Dokuments wurde das Rucio-Framework für die ATLAS- und CMS-Experimente im LHC genutzt, um die Anforderungen mit hohem Energiebedarf zu erfüllen. Er wird auch für die Bedürfnisse verschiedener wissenschaftlicher Gemeinschaften außerhalb des LHC eingesetzt, z. B. der Astrophysik. Daher muss die Dokumentation so relevant und barrierefrei wie möglich sein. Mit diesem Projekt möchte CERN den Endnutzern von Rucio eine nahtlose Nutzung des Frameworks ermöglichen, indem eine zentrale Ansicht für den Zugriff auf alle relevanten Dokumente bereitgestellt wird.

Aktueller Stand: Die Nutzerdokumentation ist derzeit an verschiedenen Stellen und in verschiedenen Formaten verfügbar, darunter wissenschaftliche Artikel, readthedocs.io mit Quellcode, Google Drive, GitHub, DockerHub oder Wikis. Mehrere Quellen führen zu Problemen beim Überwachen der Versionen und der Richtigkeit der Dokumentation. Darüber hinaus stellt ein dezentrales Dokumentationsmodell erhebliche Hürden bei der Navigation und Darstellung relevanter Informationen für einen bestimmten Anwendungsfall dar. Insbesondere bei Wikis können die Informationen für einen bestimmten Test sehr gut auf andere Instanzen in denselben oder anderen Quellen angewendet werden. Aufgrund fehlender Zusammenführung und geeigneter Verknüpfungen liegen diese Informationen jedoch brach und werden möglicherweise nicht optimal genutzt.

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

Durch die Umstrukturierung der Dokumentation soll die Navigation für Endnutzer vereinfacht werden. Er muss nicht auf der Suche nach Informationen in Sackgassen geraten, da diese aus Gründen der Übersichtlichkeit kategorisiert und gekennzeichnet werden. Aus administrativer Sicht wären Versionsverwaltung und Nachverfolgung einfach, da die Restrukturierung die Freiheit hätte, eine Kategorisierung nach Anforderungen zu ermöglichen. Wenn Sie die gesamte umstrukturierte Dokumentation zentralisieren, können Sie dafür sorgen, dass alle Informationen für den Nutzer sichtbar sind, ohne dass er mehrere Quellen konsultieren muss.

Analyse: Nachdem ich mir die Anforderungsbeschreibung durchgelesen und mit dem Mentoring-Team gesprochen habe, habe ich folgende Rückschlüsse auf den aktuellen Stand der Rucio-Dokumentation gezogen:

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

  • Readthedocs, gehostet von Sphinx, mit Quellcode im Code Link zum Code: https://github.com/rucio/rucio Link zu ReadtheDocs: https://rucio.readthedocs.io/de/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 in diesen Quellen hat verschiedene Formate. Google Drive bietet beispielsweise Dokumentationen in Form von Präsentationen und Dokumenten, GitHub Dateien hauptsächlich in der Markup-Sprache reStructuredText usw. Es gibt keine Versionsverwaltung und kein Tracking, was dazu führt, dass redundante Informationen in mehreren Quellen veröffentlicht werden. Die Kennzeichnung und Kategorisierung von Informationen ist nicht einheitlich. Daher sind bei der Suche Vorkenntnisse und Fachwissen erforderlich.

Angesichts der Vielzahl von Formaten und Quellen wird erwartet, dass die Informationen mit mkdocs neu strukturiert und zentralisiert werden. Um die Tools besser zu verstehen, habe ich mich mit ihrer Verwendung vertraut gemacht.

Urteil: Die vorhandene Dokumentation ist unstrukturiert und verstreut, ohne entsprechende Verknüpfungen. Außerdem fehlt es an Zentralisierung und Einheitlichkeit bei der Formatierung. Das bedeutet, dass Nutzer mehr Aufwand für Suchanfragen betreiben müssen. Solche Lücken führen auch zu unnötigem Druck auf Administratoren, Wartungstechniker und Leads, wodurch es schwierig wird, einen Community-gesteuerten Ansatz für die Wartung und Aktualisierung der Dokumentation aufrechtzuerhalten. Die Nutzer- und Mitwirkendenfreundlichkeit wird erheblich beeinträchtigt und es kommt zu wiederholten

Struktur der vorgeschlagenen Dokumentation: Nach einer gründlichen Analyse der Anforderungen habe ich beschlossen, die Hauptprobleme durch ein umstrukturiertes Dokumentationsmodell anzugehen.
Das neu strukturierte Modell ist im angehängten Mockup dargestellt. Jedes Dokument wird in eine der folgenden sieben Kategorien kategorisiert:

  • Info
  • Erste Schritte
  • Konzepte
  • Rucio-Schnittstellen
  • Aufgaben
  • Anleitungen
  • Erweitertes Know-how

Natürlich gibt es Verbesserungsmöglichkeiten, wie das Hinzufügen von Links, an denen ich nach Abschluss dieses Programms arbeiten möchte. Da mehr als 1.000 aktive Nutzer auf 500 Petabyte an Daten in Rucio zugreifen, sollte die vorgeschlagene Umstrukturierung der Dokumentation die Notwendigkeit für Nutzer, die Support-Mailingliste zu kontaktieren, deutlich reduzieren. Ziel ist es, die Nutzerfreundlichkeit zu verbessern, indem die Anzahl der Klickraten gesenkt und die Dokumentation durch Kategorisierung und Kennzeichnung leichter zugänglich gemacht wird. Alle Informationen, die aus der Perspektive von Benutzern, Betriebsabläufen und Administratoren kennen, wären mit höchstens drei Klicks verfügbar.

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

Projektziele: – Redundante Informationen aus verschiedenen Quellen analysieren und entfernen. D.h., jede Information sollte eine einzige Quelle haben. – Die vorhandene Dokumentation neu strukturieren, indem sie in verschiedene Teile unterteilt und gekennzeichnet wird – Die neu strukturierte Dokumentation in eine zentrale Ansicht auf Basis von mkdocs migrieren – Dokumentation umformatieren/importieren, die aufgrund von Dateiformateinschränkungen nicht migriert werden kann – Community-gestützte Änderungen an der Dokumentation einrichten, um Lücken in Bezug auf Verknüpfungen, Aktualisierungen von Informationen oder Fehlerkorrekturen zu schließen.

Die Grundvoraussetzungen für dieses System sind bereits vorhanden, aber mein Modell würde das vorhandene System verbessern, indem es geeignete Richtlinien für Beitrag und Governance mit einer entsprechenden Dokumentation aufstellen würde. Außerdem möchte ich GitHub-Projektboards einbinden, um Probleme und den Gesamtzustand des Projekts im Blick zu behalten.

Zeitplan: - Vor dem 16. August --> Mich mit den aktuellen Versionen von Dokumentation und Rucio vertraut machen --> Neue Techniken und technische Schreibfähigkeiten erlernen, die während der Laufzeit des Projekts hilfreich sind --> Einen Beitrag zu Dokumentationsproblemen leisten, die auf GitHub gemeldet werden

  • Community-Bindung (17. August bis 13. September) --> Kommunikationskanal und Zeit festlegen, um die Zeitzonendifferenz zu berücksichtigen (Pune ist 3 Stunden und 30 Minuten voraus) --> Wichtige Probleme identifizieren, um die Ziele zu verfeinern --> Durch Gespräche mehr über die Community, die Organisation und das Framework erfahren. --> Bewertung der vorgeschlagenen Dokumentationsstruktur mit Mentoren und anderen wichtigen Mitgliedern der Organisation im Hinblick auf die Durchführbarkeit und die Durchführbarkeit der Implementierung. --> Abschließen der vorgeschlagenen Funktionen und aller anderen Änderungen, die an der vorhandenen Dokumentation vorgenommen werden müssen.

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

--> Meilenstein 1: Kategorisieren und Kennzeichnen Termin: 28. September 2020 Die Zusammenführung der verfügbaren Dokumentation und das Kennzeichnen der einzelnen Elemente würde die Umstrukturierung und Bereinigung erheblich vereinfachen.

--> Meilenstein 2: Analyse, Kürzung und Neustrukturierung Fällig: 19. Oktober 2020 Die während Meilenstein 1 kategorisierte Dokumentation wird auf Duplikate und redundante Informationsquellen geprüft. Wie in den Projektinformationen angegeben, haben wir uns für alle verfügbaren Informationen an einer einzigen verlässlichen Informationsquelle interessiert.

--> Meilenstein Nr. 3: Zentralisierung und Neuformatierung: ETC: 9. November 2020 Sobald die Dokumentation gekürzt und umstrukturiert wurde, würde ich sie zuerst neu formatieren. Aufgrund der verschiedenen Quellen sind die Formate unterschiedlich und müssen zuerst in ein geeignetes Format umgewandelt werden. Danach wird die Zentralisierung vereinfacht.

--> Meilenstein 4: Tracking-Boards einrichten und Dokumentation zu Governance/Beiträgen erstellen FESTZEITPUNKT: 23. November 2020 In dieser Phase soll sichergestellt werden, dass die Dokumentation nach Abschluss des Projekts weiterhin auf dem neuesten Stand bleibt. Wenn Sie Richtlinien festlegen und Projektboards einrichten, wird es für die Administratoren einfacher, Beiträge der Community anzufordern und effektiv zu verfolgen.

--> Projektbewertung (30. November bis 5. Dezember) Projektbericht und Bewertung meiner Mentoren einreichen Bericht über meine Erfahrungen als Teilnehmer an der Season of Docs verfassen und einreichen.

Warum dieses Projekt? Ich bin der Meinung, dass Code nur durch eine gut geschriebene und versionierte Dokumentation weiter verbreitet und besser genutzt werden kann. Ich persönlich war fasziniert davon, wie das CERN wegweisende Forschung in verschiedenen Bereichen der Physik getan hat. Angesichts des Umfangs der Informationen, die während solcher Experimente verarbeitet, übertragen und generiert wurden, war ich immer fasziniert davon, wie Daten für Referenzzwecke und die zukünftige Verwendung innerhalb des Unternehmens verwaltet werden. Es wäre mir eine Ehre, zur Verbesserung der Dokumentation eines Frameworks beizutragen, das einige erstaunliche wissenschaftliche Forschungen und Entdeckungen ermöglicht hat.

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

Ich arbeite bereits an der Änderung der vorhandenen Dokumentation für Kubernetes. Aufgrund dieser Beiträge wurde ich als Release Docs Shadow für den Kubernetes-Release-Zyklus 1.19 rekrutiert. Dort trage ich dazu bei, die Dokumentation für neue Funktionen, die während der Releases hinzugefügt werden, effektiv zu pflegen und zu aktualisieren. Ich bin der Meinung, dass eine gute Dokumentation das Rückgrat eines guten Produkts/Dienstes ist. Ob verfahrenstechnisch oder technisch – gut formulierte, prägnante und leicht zugängliche Informationen würden einen Anstoß dafür geben, die Einführung voranzutreiben und eine bessere Nutzung zu ermöglichen. Da ich während meiner gesamten Karriere mit datengesteuerten verteilten Systemen gearbeitet habe, bin ich der Meinung, dass ich am besten in der Lage bin, die Komplexitäten der Anforderungen in Bezug auf die Dokumentation für solche Systeme zu verstehen. Da ich selbst Endnutzer bin, kenne ich die Fallstricke einer schlecht geschriebenen/falschen Dokumentation und werde diese bei der Umstrukturierung berücksichtigen.