Ta strona zawiera szczegóły projektu technicznego do pisania w sezonie 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ę pracować nad ujednoliceniem organizacji SciML, ponieważ jest tu wiele możliwości poprawy, a ukończenie tego projektu przyniesie niewątpliwie natychmiastowe korzyści zarówno programistom Julia, jak i aktywnym autorom i konserwatystom SciML. Pakiety rozsiane w SciML oferują naprawdę przydatne narzędzia, ale zawsze istnieje niebezpieczeństwo, że mogą zostać niezauważone (zwłaszcza przez nowych użytkowników) tylko dlatego, że użytkownik nie był w stanie ich znaleźć i zastosować do danego problemu.
Jest to dość frustrujące, ponieważ głównym celem tych pakietów jest dotarcie do szerokiego grona programistów (zarówno początkujących, jak i zaawansowanych). Aby uniknąć opisanej powyżej sytuacji, proponuję dogłębne zmodyfikowanie „pierwszej strony” dokumentacji SciML i utworzenie swego rodzaju centrum, w którym użytkownicy będą mogli przeglądać powiązane pakiety i poznawać rozwijający się ekosystem. Może też służyć jako punkt odniesienia dla bardziej doświadczonych użytkowników oraz umożliwić im wydajniejszą pracę.
Przede wszystkim istniejąca dokumentacja wszystkich pakietów wymaga przeredagowania pod kątem najbardziej podstawowych problemów stylistycznych (takich jak ortografia, interpunkcja, gramatyka itp.). Aby zapewnić spójność stylistyczną, SciML musi zawierać konkretny przewodnik po stylu (niezbędny do wprowadzania zmian wstecznych i do celów informacyjnych). Zaczynanie od zera byłoby stratą czasu. Zamiast tego powinien on być oparty na istniejących konwencjach Julia i zawierać nowe wpisy dotyczące problemów związanych z SciML.
Po ukończeniu przewodnika po stylach zamierzam poprawić obecną dokumentację w ramach drugiej fazy projektu. Dzięki temu dokumentacja będzie wyglądać bardziej profesjonalnie i stabilnie. Utworzyłem już kilka pull requestów, które ilustrują moje podejście do tego zadania. W tej fazie zamierzam też opracować (i wdrożyć) wydajny system cytowania. Pierwszym zadaniem będzie zaktualizowanie strony z nieaktualnymi cytatami.
Trzeci etap, który jest prawdopodobnie najważniejszy, obejmie opracowanie planu SciML, który podkreśli wzajemne oddziaływanie rozproszonych pakietów. Im większa spójność między 2 pakietami (w związku z problemem lub samym kodem), tym bliżej siebie powinny się one znajdować na liście „Zobacz też”. Proponuję utworzyć 2 klucze rekomendacji: jeden dla podobieństwa kodu, a drugi dla podobieństwa problemów. W ten sposób użytkownicy będą mogli znajdować inne potencjalnie przydatne pakiety o wiele szybciej niż podczas żmudnego przeglądania odpowiednich repozytoriów i dokumentacji. Zamiast wymieniać wszystkie możliwe połączenia między pakietami, skupię się na większych pakietach i spróbuję przedstawić ich połączenia z mniejszymi pakietami (ta metoda zostanie również rozszerzona o samouczki, w których należy wskazać połączenie z innym pakietem). Takie podejście gwarantuje, że listy „zobacz też” będą zawierać przydatne informacje, ale nie będą one wyczerpującym wyliczeniem kombinacji pakietów.