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:
- Jan
- Nazwa projektu:
- CERN-HSF – Dokumentacja ROOT na potrzeby ogólnej akceptacji odbiorców, dynamiczne powiązania Pythona i samouczki
- Długość projektu:
- Długotrwałe (5 miesięcy)
Opis projektu
CERN-HSF – Dokumentacja ROOT „General Audience Adoption”, „Dynamic Python Bindings, and tutorials” Mentor: Olivier Couet, Axel Naumann
Streszczenie: Dokumentacja jest niezbędna do skutecznego i skutecznego wdrożenia oprogramowania przez użytkowników. Jasna, dokładna i obszerna dokumentacja użytkownika ułatwia użytkownikom biegłość w korzystaniu z oprogramowania zgodnie z założeniami ich celów. A związane z nim konkretne przykłady i samouczki stanowią potężne narzędzie, dzięki któremu użytkownicy mogą szybko się nauczyć.
Badając wykorzystanie ROOT przez fizyków, badaczy i programistów w zakresie analizy i wizualizacji danych w fizyce, zdajemy sobie sprawę z korzyści zapewnianych przez przyjazną dla użytkownika i zaktualizowaną dokumentację. Szeroki zakres kodu źródłowego i jego rozwój sprawiają, że system dokumentacji powinien korzystać z równoległego rozwoju, aby maksymalnie wykorzystywać wszystkie możliwości ROOT.
Podsumowanie i analiza bieżącej dokumentacji Obecnie dokumentacja użytkownika zawiera przewodnik, który pozwala fizykom łatwiej wdrożyć ROOT w porównaniu z ogółem odbiorców. Ponadto w przypadku niektórych tematów, takich jak dynamiczne powiązania w Pythonie, można wprowadzić ulepszenia, aby dokumentacja była bardziej kompleksowa i przejrzysta. Podobnie nowy format danych RNTuple nie ma niezbędnych szczegółowych specyfikacji. W obecnej dokumentacji brakuje samouczków związanych z ROOT 7.
Metodologia: Po konsultacjach z Olivierem okazało się, że w celu rozwiązania wspomnianych wyżej problemów należy skupić się przede wszystkim na identyfikacji braków w wiedzy między specjalistycznymi badaczami a odbiorcami, opracowanie dokumentacji, która pomoże wypełnić tę lukę, opracowanie bardziej szczegółowej dokumentacji funkcji Dynamic Python Bindings, wdrożenie „samouczków na potrzeby nowoczesnej analizy” dla ROOT 7 oraz opracowanie szczegółowych specyfikacji technicznych dla RNTuple. W ramach tego procesu dokumentacja może obejmować notatniki Jupyter, tak aby fizyczne i interaktywne narzędzia do nauki mogły pomagać użytkownikom.
Oś czasu: Etapy projektu powinny obejmować: Identyfikowanie braków w wiedzy między specjalistami i ogólną grupą odbiorców (podczas czytania aktualnej dokumentacji i kodu źródłowego) → 1–2 tygodnie Utworzenie i refaktoryzowanie dokumentacji w celu zniwelowania tej luki → 3 tygodnie Opracowanie bardziej szczegółowej dokumentacji dotyczącej dynamicznych wiązań w Pythonie → 3 tygodnie Wdrożenie samouczków dotyczących dynamicznych wiązań w Pythonie → 3 tygodnie Wdrożenie samouczków dotyczących dynamicznych wiązań w Pythonie → 3 tygodnie
Materiały dostarczane i wytyczne dotyczące sukcesu: pojedyncza, ujednolicona dokumentacja użytkownika bez żadnych luk Całkowicie zaktualizowana dokumentacja dla użytkowników uwzględniająca najnowsze funkcje, np. nowe klasy derywowane Samouczki w notatnikach Jupyter