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
- Specjalista ds. technicznych:
- John
- Nazwa projektu:
- CERN-HSF – dokumentacja ROOT dla ogółu odbiorców, dynamiczne przekształcenia Pythona i samouczki
- Długość projektu:
- Długookresowa (5 miesięcy)
Opis projektu
CERN-HSF – dokumentacja ROOT dla użytkowników ogólnych, dynamiczne przekształcenia Pythona i samouczki Mentor: Olivier Couet, Axel Naumann
Streszczenie: Dokumentacja jest niezbędna do skutecznego i skutecznego wdrażania oprogramowania przez użytkowników. Jasna, dokładna i pełna dokumentacja ułatwia użytkownikom naukę obsługi oprogramowania, które pomaga im osiągnąć ich cele. W tym celu szczegółowe przykłady i samouczki stanowią potężne narzędzia, które pomagają użytkownikom szybko się uczyć.
Badając wykorzystanie ROOT przez fizyków, badaczy i programistów w obszarze analizy i wizualizacji danych w fizyce, dostrzegamy korzyści płynące z przyjaznej dla użytkownika i aktualnej dokumentacji. Ze względu na szerokość i stale rosnącą liczbę wierszy kodu źródłowego system dokumentacji powinien być rozwijany równolegle, aby użytkownicy mogli w pełni korzystać z wszystkich możliwości ROOT.
Podsumowanie i analiza bieżącej dokumentacji Aktualnie w dokumentacji użytkownika znajduje się przewodnik, który pozwala fizykom łatwiej wdrożyć ROOT w porównaniu do ogółu odbiorców. Ponadto w przypadku niektórych tematów, takich jak dynamiczne wiązania Pythona, można wprowadzić ulepszenia, aby dokumentacja była bardziej obszerna i jasna. Podobnie jest w nowym formacie danych RNTuple, któremu brakuje wymaganych szczegółowych specyfikacji. W obecnej dokumentacji brakuje samouczków dotyczących ROOT 7.
Metodologia: po konsultacjach z Olivierem okazało się, że aby rozwiązać powyższe problemy, należy przede wszystkim wypełnić luki w wiedzy między specjalistycznymi badaczami a ogólnymi odbiorcami, opracować dokumentację, która wypełni te luki, napisać bardziej szczegółową dokumentację Dynamic Python Bindings, wdrożyć „samouczki dotyczące nowoczesnej analizy” dla ROOT 7 i opracować szczegółowe specyfikacje techniczne dla RNTuple. W tym celu dokumentacja może zawierać notatki Jupyter, aby użytkownicy mogli korzystać z wyraźnych i interakcyjnych narzędzi do nauki.
Etapy projektu: szacujemy liczbę etapów projektu: identyfikacja luk w wiedzy między wyspecjalizowanymi badaczami a ogólną grupą odbiorców (po zapoznaniu się z obecną dokumentacją i kodem źródłowym) → 1–2 tygodnie Opracowanie i refaktoryzacja dokumentacji w celu wypełnienia tej luki
Wymagania i wskazówki: Jednolita, ujednolicona dokumentacja dla użytkowników bez żadnych luk. Całkowicie zaktualizowana dokumentacja dla użytkowników, która odzwierciedla najnowsze funkcje, np. nowe klasy pochodne. Samouczki w notatnikach Jupyter.