Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- Język Julii
- Pisarz techniczny:
- mkg33
- Nazwa projektu:
- Ujednolicona dokumentacja Scientific Machine Learning
- Długość projektu:
- Długotrwałe (5 miesięcy)
Opis projektu
Chcę popracować nad ujednoliceniem organizacji SciML, ponieważ ma ona ogromny potencjał do poprawy w tej dziedzinie, a ukończenie tego projektu przyniesie natychmiastowe korzyści zarówno programistom Julii, jak i aktywnym współtwórcom SciML. Pakiety rozsiane w języku SciML oferują naprawdę przydatne narzędzia, ale zawsze istnieje ryzyko, że nie zostaną zauważone (zwłaszcza przez nowych użytkowników) ze względu na to, że użytkownik nie może odkryć pakietu i zastosować go w danym problemie.
Jest to dosyć frustrujące, ponieważ pakiety mają przede wszystkim umożliwić dotarcie do szerokiego grona programistów (zarówno początkujących, jak i ekspertów). Aby uniknąć opisanej powyżej sytuacji, proponuję gruntowne przeredagowanie „pierwszej strony” dokumentacji SciML i stworzenie swego rodzaju centrum, w którym użytkownicy będą mogli przeglądać powiązane pakiety i poznawać rozwijający się ekosystem. Może być też cennym punktem odniesienia dla bardziej doświadczonych użytkowników, który pomoże im wydajniej pracować.
Przede wszystkim konieczna jest poprawa bieżącej dokumentacji wszystkich pakietów aplikacji pod kątem podstawowych problemów stylistycznych (np. ortograficznych, interpunkcyjnych, gramatycznych itp.). Aby zapewnić spójność stylistyczne, SciML musi mieć konkretny przewodnik dotyczący stylu (niezbędny przy wprowadzaniu zmian wstecznych i na przyszłym podejściu do niego). Gdybym zaczynał od zera, to strata czasu. Powinien on być oparty na obecnych konwencjach Julii i zawierać nowe fragmenty w przypadku problemów specyficznych dla SciML.
Po przygotowaniu wskazówek dotyczących stylu zamierzam poprawić bieżącą dokumentację w drugim etapie projektu. Dzięki temu dokumentacja będzie wyglądać bardziej profesjonalnie i stabilnie. Utworzyłem już kilka żądań pull, które ilustrują moje podejście do tego zadania. Na tym etapie chcę też opracować (i wdrożyć) skuteczny system cytowania. Pierwszą czynnością będzie zaktualizowanie nieaktualnej strony z opisami cytatów.
Trzecia faza, zapewne najważniejsza, będzie polegała na opracowaniu planu rozwoju SciML, który podkreśli zależności między rozproszonymi pakietami. Im silniejsza jest spójność między 2 pakietami (pod względem problemu lub samego kodu), tym bliżej powinny one pojawić się na liście „Zobacz też”. Proponuję utworzyć 2 klucze rekomendacji: jeden dla podobieństwa kodu i drugi dla podobieństwa problemów. W ten sposób użytkownicy będą mogli identyfikować inne potencjalnie przydatne pakiety znacznie szybciej niż muszą oni przeglądać odpowiednie repozytoria i dokumenty. Zamiast wymieniać wszystkie możliwe połączenia między pakietami, skupmy się na większych z nich i postaram się prezentować ich linki z mniejszymi pakietami (ta metoda zostanie również rozszerzona do aktualizacji samouczków, w których należy wskazać połączenie z innym pakietem). Takie podejście daje gwarancję, że lista „Zobacz też” będzie zawierać przydatne informacje, ale nie zawiera wyczerpujących list kombinacji pakietów.