projekt CERN-HSF

Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.

Podsumowanie projektu

Organizacja open source:
CERN-HSF
Pisarz techniczny:
Alicja
Nazwa projektu:
Rucio – modernizacja (restrukturyzacja i przeredagowanie) dokumentacji Rucio
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

Streszczenie: Schemat Rucio został opracowany w celu zarządzania dużymi ilościami rozproszonych geograficznie danych naukowych w centrach danych heterogenicznych oraz porządkowaniu ich. Dzięki funkcjom, takim jak rozproszone odzyskiwanie danych i replikacja adaptacyjna, platforma jest wysoce skalowalna, modułowa i rozszerzalna. Klienci korzystający z dokumentacji takiej usługi pochodzą z różnych środowisk i mają różne wymagania związane z dostępem do niej. Dobra dokumentacja takiej usługi powinna więc uprościć wdrażanie i wykorzystywanie przez użytkowników, a jednocześnie stanowić źródło informacji o typowych problemach i ich rozwiązaniach.

Bez takiej dokumentacji występowałyby poważne przeszkody w efektywnym wykorzystaniu. Może to zwiększyć koszty pomocy technicznej i narazić na ryzyko reputacji firmy. Dokumentacja to przecież sposób komunikacji. Dlatego zadbanie o to, aby komunikacja była skuteczna i dobrze uporządkowana, a jednocześnie zachowana została przydatna przy odpowiedniej obsłudze wersji, jest łatwiejsza w obsłudze.

W momencie tworzenia tego tekstu do realizacji wymagań energetycznych w eksperymentach ATLAS i CMS wykorzystano platformę Rucio. Jest on również używany na potrzeby różnych społeczności naukowych spoza LHC, takich jak astrofizyka, dzięki czemu dokumentacja musi być jak najbardziej trafna i przystępna. Dzięki temu projektowi CERN chce umożliwić użytkownikom aplikacji Rucio bezproblemowe korzystanie z platformy, zapewniając scentralizowany widok z dostępem do całej odpowiedniej dokumentacji.

Obecny stan: Obecnie dokumentacja dla użytkowników jest rozpowszechniana w różnych miejscach i ma wiele formatów, w tym artykuły naukowe, Readthedocs.io ze źródłem w kodzie, Dysk Google, GitHuba, DockerHuba czy witryny Wikis. Duża liczba źródeł powoduje problemy ze śledzeniem wersji i poprawnością dokumentacji. Poza tym zdecentralizowany model dokumentacji stwarza znaczne utrudnienia w nawigacji i wyświetlaniu informacji istotnych dla danego przypadku użycia. Szczególnie w przypadku witryn Wiki informacje podane na temat konkretnego eksperymentu mogą mieć zastosowanie również do innych przypadków pochodzących z tego samego źródła lub z innych źródeł. Jednak ze względu na brak konsolidacji i odpowiednich połączeń te informacje pozostają uśpione i potencjalnie niedostatecznie wykorzystywane.

Dlaczego zaproponowana przez Ciebie dokumentacja dla użytkowników jest ulepszona w stosunku do obecnej? Ze względu na wieloaspektowy problem proponowany poniżej model eliminuje problemy z nawigacją, obsługą wersji, śledzeniem i wyświetlaniem dokumentacji, jak opisano poniżej:

Zmiana struktury dokumentacji ma na celu uproszczenie działań związanych z poruszaniem się po stronie użytkownika. Nie musi zagłębiać się w króliki podczas szukania informacji, ponieważ zostaną one skategoryzowane/oznaczone dla uproszczenia. Z perspektywy administracyjnej obsługa wersji i śledzenie byłaby uproszczona, ponieważ zmiana struktury zapewniłaby swobodę kategoryzowania na podstawie wymagań. Scentralizowanie całej przeredagowanej dokumentacji zapewni, że wszystkie informacje będą widoczne dla użytkownika bez konieczności odwoływania się do wielu źródeł.

Analiza: Po zapoznaniu się ze zwięzłymi wymaganiami i rozmowach z zespołem mentora widzę, że moje odliczenia w aktualnym stanie dokumentacji Rucio wyglądają tak:

Istnieje 6 głównych źródeł dokumentacji: – Link do Dysku Google : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7

  • Przeczytaj dokumenty obsługiwane przez Sphinxa ze źródłem w kodzie Link do kodu: https://github.com/rucio/rucio Link do ReadtheDokumentacja: https://rucio.readthedocs.io/en/latest/

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

  • Link na GitHubie: https://github.com/rucio/rucio

  • Link w witrynie Wiki: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/Atlas DistributiondComputing

  • Artykuły naukowe Link: https://arxiv.org/abs/1902.09857

Dokumentacja z tych źródeł ma różne formaty. Na przykład na Dysku Google mamy dokumentację w formie Prezentacji i Dokumentów, a na GitHubie pliki głównie w języku znaczników reStructuredText itp. Brak obsługi wersji i śledzenia, co prowadzi do publikowania zbędnych informacji w wielu źródłach. Nie ma spójności w oznaczaniu i kategoryzacji informacji. Dlatego podczas wyszukiwania musisz wykazać się doświadczeniem i doświadczeniem.

Ze względu na różnorodność formatów i źródeł oczekuje się restrukturyzacji informacji i scentralizowania ich za pomocą mkdocs. Aby lepiej zrozumieć te narzędzia, przeanalizowałem i zapoznałem się z ich wykorzystaniem.

Ocena: istniejąca dokumentacja jest nieuporządkowana i jest rozproszona bez odpowiednich połączeń. Brakuje też w nim centralizacji i spójności formatowania. To sprawia, że użytkownicy muszą poświęcić więcej czasu na wyszukiwanie. Takie luki nakładają się również na niepotrzebną presję na administratorów, menedżerów i kierowników, co utrudnia utrzymanie opartego na społeczności podejścia do konserwacji i aktualizacji dokumentacji. Znaczne pogorszenie komfortu użytkowania i współpracy będzie się pogorszyło,

Struktura proponowanej dokumentacji: Po dokładnym przeanalizowaniu wymagań zdecydowaliśmy się zająć się najważniejszymi problemami za pomocą nowego modelu dokumentacji.
Zrestrukturyzowany model jest przedstawiony w załączonej poniżej przykładowej formie. Każda dokumentacja zostanie sklasyfikowana w tych 7 kategoriach:

  • Informacje
  • Pierwsze kroki
  • Pojęcia
  • Interfejsy Rucio
  • Zadania
  • Samouczki
  • Zaawansowana wiedza

Są oczywiście pewne ulepszenia, takie jak dodawanie linków, nad którymi chciałbym pracować po zakończeniu tego programu. Ponad 1000 aktywnych użytkowników ma dostęp do 500 petabajtów danych w Rucio, więc proponowana zmiana struktury dokumentacji powinna znacznie ograniczyć konieczność utrzymywania się na liście adresowej. Ma to na celu poprawę wrażeń użytkowników przez zmniejszenie liczby kliknięć i łatwiejsze przedstawienie dokumentacji za pomocą kategorii i etykiet. Wszystko, co można się dowiedzieć z perspektywy użytkownika, operacji lub personelu administracyjnego, powinno być dostępne po maksymalnie 3 kliknięciach.

Link do przykładu: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

Cele projektu: – Analiza i usuwanie zbędnych informacji pochodzących z różnych źródeł, tj. każdy element informacji powinien mieć jedno źródło wiarygodnych informacji. – Zmień strukturę przez dodanie etykiet i podziel ją na kategorie. – Przenieś przerobioną dokumentację do scentralizowanego widoku na podstawie plików mkdocs. – Przeformatuj/importuj dokumentację, której nie można przenieść z powodu ograniczeń formatu pliku. – Skonfiguruj edycję dokumentów wykonywaną przez społeczność, aby uzupełnić brakujące luki w dotychczasowych powiązaniach, aktualizacji informacji czy korygowaniu błędów.

Podstawowe cechy tego systemu zostały już wdrożone, ale mój model mógłby ulepszyć istniejący system, podając odpowiednie wytyczne dotyczące wkładu i zarządzania z odpowiednią dokumentacją. Rozważam też wykorzystanie tablic projektów GitHub do śledzenia problemów i ogólnej kondycji projektu.

Oś czasu: – Przed 16 sierpnia --> Zapoznanie się z aktualnymi wersjami dokumentacji i Rucio --> Poznawanie nowych technik i technicznych umiejętności pisania przydatnych w trakcie projektu --> Wspieranie problemów z dokumentacją zgłaszanych na GitHubie

  • Nawiązywanie więzi ze społecznością (17 sierpnia–13 września) -> Skonfiguruj kanał komunikacji i określ czas, który uwzględnia różnice w strefach czasowych (Pune ma 3 godziny i 30 minut do przodu) --> Główne problemy, które należy rozpoznać przy ustalaniu celów --> Dowiedz się więcej o społeczności, organizacji i strukturze, uczestnicząc w rozmowach. --> Ocena proponowanej struktury dokumentacji wraz z mentorami i innymi kluczowymi członkami organizacji w celu zapewnienia możliwości i wykonalności wdrożenia. --> Sfinalizowanie proponowanych funkcji i wprowadzenie wszelkich innych zmian, które mogą być konieczne w dotychczasowej dokumentacji.

  • Okres dokumentacji (14 września – 30 listopada) Na podstawie omówionego tu proponowanego formatu przedstawiliśmy zestawienie najważniejszych kamieni milowych, które planuję osiągnąć w tym okresie.

--> Etap 1: kategoryzowanie i oznaczanie etykietami Szacowany czas dotarcia na miejsce: 28 września 2020 r. Zapewnienie łatwości dostępu do dostępnej dokumentacji i oznaczenie jej etykietami znacznie uprościłoby proces restrukturyzacji i przycinania treści.

--> Etap 2. Analiza, przycinanie i restrukturyzacja ETC: 19 października 2020 r. Dokumentacja, która została sklasyfikowana na pierwszym etapie, będzie analizowana pod kątem duplikatów i zbędnych źródeł informacji. Zgodnie z informacjami o projekcie wszystkie dostępne informacje kierujemy na jedno źródło wiarygodnych informacji.

--> Etap 3. Centralizacja i zmiana formatu: ETC: 9 listopada 2020 r. Po odpowiednim przycięciu i przeorganizowaniu dokumentacji należy zacząć od jej zmiany formatu. Ze względu na różne źródła formaty są różne i najpierw trzeba je przekształcić, aby uzyskać odpowiedni format. Usprawniłoby to proces centralizacji.

--> Etap 4: konfiguracja platform śledzących i dokumentacja dotycząca zarządzania i wpłat ETR: 23 listopada 2020 r. Ten etap ma na celu zapewnienie, że po zakończeniu projektu dokumentacja będzie stale aktualizowana. Opracowanie wytycznych i przygotowanie komisji projektowych odciąży członków administracyjnych w zachęcaniu ich do otrzymywania darowizn od społeczności i skutecznym ich monitorowaniu.

--> Ocena projektu (30 listopada–5 grudnia) Prześlij raport z projektu i ocenę mentorów Napisz i prześlij raport na temat moich doświadczeń jako uczestnika sezonu Dokumentów.

Dlaczego ten projekt? Sądzę, że uzupełnienie kodu dobrze napisaną i wersjonowaną dokumentacją to jedyny sposób na dalsze wdrażanie i lepsze wykorzystanie aplikacji. Fascynuje mnie też sposób, w jaki CERN prowadzi nowatorskie badania w różnych dziedzinach fizyki. Biorąc pod uwagę skalę przetworzonych, przekazywanych i generowanych informacji podczas takich eksperymentów, zawsze mnie intrygowałem, jak zarządza się danymi do celów referencyjnych i wykorzystywania ich w przyszłości w organizacji. To zaszczyt okazać się pomocnym w ulepszaniu dokumentacji struktury, na której opiera się kilka niesamowitych badań naukowych i odkryć.

Dlaczego jestem odpowiednią osobą do tego projektu? Oprócz spełnienia wymagań wstępnych jestem pewien, że byłbym odpowiednią osobą do tego projektu, ponieważ:

Modyfikuję już istniejącą dokumentację Kubernetes. Dzięki tym działaniom znalazłem się w katalogu dokumentów wersji w ramach cyklu wersji Kubernetes 1.19, w którym uczestniczę w efektywnym zarządzaniu i uaktualnianiu dokumentacji nowych funkcji, które pojawiają się w kolejnych wersjach. Uważam, że dobra dokumentacja jest podstawą dobrego produktu/usługi. Dobrze napisane, zwięzłe i przystępne informacje, bez względu na to, czy chodzi o procedury czy kwestie techniczne, będą oddziaływać na ten proces i zwiększą jego wykorzystanie. Przez całą swoją karierę współpracowałem z systemami rozproszonymi opartymi na danych, więc uważam, że mam najlepsze możliwości zrozumienia zawiłości w wymaganiach w odniesieniu do dokumentacji takich systemów. Jako użytkownik końcowy znam pułapki źle napisanej lub nieprawidłowej dokumentacji i z wszystkim uwzględnię te problemy podczas restrukturyzacji.