Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.
Podsumowanie projektu
- Organizacja open source:
- CERN-HSF
- Pisarz techniczny:
- Ariadne
- Nazwa projektu:
- Rucio – unowocześnienie (przestrukturyzowanie i przepisanie) dokumentacji Rucio
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Streszczenie: Framework Rucio został opracowany w celu zarządzania dużymi ilościami danych naukowych rozproszonych geograficznie w różnorodnych centrach danych i ich organizacji. Oferuje ona funkcje takie jak rozproszone odzyskiwanie danych i adaptacyjna replikacja. Jest to wysoce skalowalna, modułowa i rozszerzalna platforma. Odbiorcy dokumentacji dotyczącej takiej usługi pochodzą z różnych środowisk i mają różne wymagania w zakresie dostępu do usług. Dobra dokumentacja takiej usługi powinna uprościć jej wdrażanie i wykorzystanie przez użytkowników, a także służyć jako materiał referencyjny w przypadku typowych problemów i rozwiązywania problemów.
Bez takiej dokumentacji występowałyby znaczne przeszkody w wydajnym i efektywnym wykorzystaniu. Może to spowodować wzrost kosztów obsługi i stanowić zagrożenie dla reputacji marki produktu. Dokumentacja to przecież forma komunikacji. Zapewnienie odpowiedniej wersji komunikacji w ramach łatwego w obsłudze i dostępnego frameworku, który jest jednocześnie trafny, to klucz do sukcesu.
W momencie pisania tego tekstu framework Rucio był wykorzystywany do obsługi dużych wymagań energetycznych eksperymentów ATLAS i CMS w LHC. Wykorzystuje się je też w celu zaspokajania potrzeb różnych społeczności naukowych poza LHC, takich jak astrofizyka, dlatego dokumentacja powinna być jak najbardziej trafna i przystępna. Dzięki temu projektowi CERN chce zapewnić użytkownikom Rucio bezproblemowe korzystanie z ramy, oferując im scentralizowany widok z dostępem do całej dokumentacji.
Obecny stan: Obecnie dokumentacja użytkownika jest rozproszona w różnych miejscach i występuje w różnych formatach, takich jak artykuły naukowe, readthedocs.io z kodem źródłowym, Dysk Google, GitHub, DockerHub czy Wikis. Wiele źródeł powoduje problemy z śledzeniem wersji i poprawnością dokumentacji. Poza tym zdecentralizowany model dokumentacji powoduje znaczne trudności w nawigacji i wyświetlaniu odpowiednich informacji w przypadku danego zastosowania. Szczególnie w przypadku Wikipedii informacje podane w ramach konkretnego eksperymentu mogą być przydatne również w przypadku innych instancji znajdujących się w tych samych lub innych źródłach. Jednak ze względu na brak konsolidacji i odpowiednie powiązania te informacje są uśpione i mogą być niedostatecznie wykorzystywane.
Dlaczego proponowana przez Ciebie dokumentacja użytkownika jest lepsza od obecnej? Ze względu na złożoność problemu proponowany poniżej model eliminuje przeszkody związane z nawigacją, wersjonowaniem, śledzeniem i wyświetlaniem dokumentacji:
Zmiana struktury dokumentacji ma na celu uproszczenie nawigacji po stronie użytkownika. Nie musi on tracić czasu na szukanie informacji, ponieważ będą one pogrupowane i opisane. Z perspektywy administracyjnej ułatwi to wersjonowanie i śledzenie, ponieważ restrukturyzacja zapewni swobodę kategoryzowania na podstawie wymagań. Centralizacja całej przebudowanej dokumentacji zapewniłaby, że wszystkie informacje będą widoczne dla użytkownika bez konieczności korzystania z wielu źródeł.
Analiza: po przeczytaniu zestawienia wymagań i rozmowach z zespołem mentorów moje wnioski dotyczące obecnego stanu dokumentacji Rucio są następujące:
Istnieje 6 głównych źródeł dokumentacji: - link do Dysku Google : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
Readthedocs oparty na Sphinxie z źródłem w kodzie Link do kodu: https://github.com/rucio/rucio Link do ReadtheDocs: https://rucio.readthedocs.io/pl/latest/
DockerHub Link: https://hub.docker.com/u/rucio
GitHub Link: https://github.com/rucio/rucio
Link do Wikis: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
Artykuły naukowe Link: https://arxiv.org/abs/1902.09857
Dokumentacja tych źródeł jest dostępna w różnych formatach. Na przykład Dysk Google zawiera dokumentację w postaci prezentacji i dokumentów, GitHub zawiera głównie pliki w języku znaczników reStructuredText itd. Brak wersji i śledzenia prowadzi do publikowania nadmiarowych informacji w różnych źródłach. Brak jednolitości w etykietowaniu i kategorizowaniu informacji. Dlatego podczas wyszukiwania wymagane jest wcześniejsze doświadczenie i wiedza.
Z powodu ogromnej liczby formatów i źródeł oczekuje się, że informacje zostaną przebudowane i scentralizowane za pomocą mkdocs. Aby lepiej poznać te narzędzia, zgłębiłam ich temat i zapoznałam się z ich zastosowaniem.
Werdykt: Istniejąca dokumentacja jest nieuporządkowana i rozproszona bez odpowiednich połączeń. Brakuje też centralizacji i jednolitości formatowania. W efekcie użytkownicy muszą poświęcić więcej czasu na wyszukiwanie. Te braki wywierają też niepotrzebną presję na administratorów, administratorów i potencjalnych klientów. Z tego powodu utrzymanie lokalnego podejścia do konserwacji i aktualizowania dokumentacji staje się trudne. Wrażenia użytkowników i współtwórców są znacznie gorsze, a reklamy będą się powtarzać.
Struktura proponowanej dokumentacji: po dokładnej analizie wymagań zdecydowałem się rozwiązać główne problemy za pomocą przebudowanego modelu dokumentacji.
Nowy model przedstawiliśmy na makiecie załączonej poniżej. Każdą dokumentację można podzielić na 7 poniższych kategorii:
- Informacje
- Pierwsze kroki
- Pojęcia
- Interfejsy Rucio
- Lista zadań
- Samouczki
- Zaawansowana wiedza
Oczywiście są jeszcze usprawnienia, np. dodawanie linków, nad którymi chciałbym popracować po zakończeniu tego programu. Ponad 1000 aktywnych użytkowników korzysta z 500 petabajtów danych w Rucio. Proponowana restrukturyzacja dokumentacji powinna znacznie ograniczyć konieczność korzystania z listy mailingowej pomocy. Celem jest poprawa wrażeń użytkownika dzięki zmniejszeniu liczby kliknięć i łatwemu wyświetlaniu dokumentacji za pomocą kategoryzacji i etykiet. Wszystko, co trzeba wiedzieć z punktu widzenia użytkownika, zespołu operacyjnego lub administratora, będzie dostępne w ciągu 3 kliknięć.
Link do mockupu: 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ł. Oznacza to, że każda informacja powinna mieć jedno źródło prawdy. – Zmiana struktury przez etykiety i podzielenie istniejącej dokumentacji na różne części. – Przeniesienie dokumentacji zmodyfikowanej do scentralizowanego widoku na podstawie mkdocs. – Zmiana formatu lub importu dokumentacji, której nie można przenieść z powodu ograniczeń formatu pliku. – Skonfigurowanie przez społeczność modyfikacji dokumentacji w celu wypełnienia brakujących luk w zakresie połączeń, aktualizacji informacji lub poprawienia błędów.
Podstawowe rozwiązania tego systemu są już gotowe, jednak mój model poprawi się dzięki ustaleniu odpowiednich wytycznych dotyczących wkładu i nadzoru w ramach odpowiedniej dokumentacji. Planuję też wdrożenie tablic projektów w GitHubie do śledzenia problemów i ogólnego stanu projektu.
Harmonogram: - Przed 16 sierpnia --> Zapoznaj się z bieżącymi wersjami dokumentacji i Rucio --> Poznaj nowe techniki i umiejętności związane z pisaniem technicznym, które przydadzą się w ramach projektu --> Wskazuj problemy z dokumentacją, jeśli takie wystąpią, w GitHubie
Tworzenie więzi ze społecznością (17 sierpnia – 13 września) --> Skonfiguruj kanał komunikacji i określ czas, aby uwzględnić różnicę w strefach czasowych (Pune: wyprzedzenie 3 godziny i 30 minut) --> Główne problemy do ustalenia celów --> Dowiedz się więcej o społeczności, organizacji i platformie, prowadząc rozmowy. --> Ocena proponowanej struktury dokumentacji przez mentorów i innych kluczowych członków organizacji pod kątem możliwości wdrożenia. --> Finalizacja proponowanych funkcji i wszelkich innych modyfikacji, które mogą być potrzebne w istniejącej dokumentacji.
Okres dokumentacji (14 września–30 listopada) Na podstawie proponowanego formatu podanego tutaj podaję listę najważniejszych etapów, które planuję zrealizować w trakcie dokumentacji.
--> Osiągnięcie etapu 1: kategoryzowanie i oznaczanie etykietami ETC: 28 września 2020 r. Uwzględnienie dostępnej dokumentacji i oznaczenie jej etykietami znacznie uprości proces restrukturyzacji i usuwania zbędnych elementów.
--> Etap 2. Analiza, przycinanie i restrukturyzacja ETC: 19 października 2020 r. Dokumentacja po pogrupowaniu w ramach etapu 1 zostanie przeanalizowana pod kątem duplikatów i zbędnych źródeł informacji. Zgodnie z informacjami o projekcie wszystkie dostępne dane dotyczą jednego źródła.
--> Punkt krytyczny 3. Centralizacja i przeformatowanie: ETC: 9 listopada 2020 r. Gdy dokumentacja zostanie odpowiednio okrojona i przebudowana, najpierw spróbuję ją przeformatować. Ze względu na różne źródła formaty te są różne i najpierw trzeba przejść na odpowiedni format. Po wykonaniu tej czynności proces centralizacji będzie łatwiejszy.
--> Punkt kontrolny 4. Konfigurowanie tablic kontrolnych i dokumentacji dotyczącej zarządzania oraz wkładu ETC: 23 listopada 2020 r. Ta faza ma na celu zapewnienie, aby po zakończeniu projektu dokumentacja była nadal aktualizowana. Określenie wytycznych i utworzenie tablic projektowych ułatwi administratorom zespółowi proszenie o wkład społeczności i skuteczne śledzenie tych działań.
--> Ocena projektu (30 listopada – 5 grudnia) Przesłanie raportu z projektu i oceny mentorów Napisz i prześlij raport z uczestnictwa w sezonie Docs.
Dlaczego ten projekt? Uważam, że uzupełnienie kodu dobrze napisaną i wersjonowaną dokumentacją jest jedynym sposobem na dalsze wdrażanie i lepsze wykorzystanie. Osobiście jestem zafascynowany tym, jak CERN prowadzi pionierskie badania w różnych dziedzinach fizyki. Biorąc pod uwagę skalę informacji przetwarzanych, przesyłanych i generowanych podczas takich eksperymentów, zawsze zastanawiało mnie, jak organizacja zarządza danymi na potrzeby ich wykorzystania w przyszłości. Chcielibyśmy stworzyć lepszą dokumentację dla platformy, która umożliwiała prowadzenie niesamowitych badań naukowych i prowadzi do niesamowitych odkryć.
Dlaczego jestem odpowiednią osobą do tego projektu? Oprócz spełnienia wymagań wstępnych jestem przekonany, że jestem odpowiednią osobą do tego projektu, ponieważ:
Pracuję już nad modyfikacją istniejącej dokumentacji Kubernetes. W wyniku tych działań zostałem włączony do zespołu programistów Kubernetes jako osoba pomagająca w utrzymywaniu i ulepszaniu dokumentacji w cyklu wydawniczym 1.19. Współpracuję z nimi przy aktualizowaniu dokumentacji o nowe funkcje dodawane w ramach kolejnych wersji. Uważam, że dobra dokumentacja jest podstawą świetnego produktu lub usługi. Niezależnie od tego, czy są to informacje proceduralne czy techniczne, dobrze napisane, zwięzłe i łatwo dostępne informacje będą zachęcać do korzystania z usługi i pomagać w lepszym jej wykorzystaniu. Ponieważ przez całą swoją karierę pracowałam z systemami rozproszonymi opartymi na danych, uważam, że najlepiej znam szczegóły wymagań związanych z dokumentacją takich systemów. Jestem użytkownikiem, więc znam pułapki związane z niewłaściwie napisaną lub niepoprawną dokumentacją i chcę je uwzględnić podczas wprowadzania zmian.