Ta strona zawiera szczegółowe informacje na temat projektu dotyczącego pisania technicznego zaakceptowanego do udziału w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- SciPy
- Pisarz techniczny:
- mkg33
- Nazwa projektu:
- Dokumentacja dla użytkowników i dokładna zmiana struktury
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Motywacja:
Zamierzam zrefaktoryzować istniejącą dokumentację, aby były łatwo dostępne dla użytkowników o różnych potrzebach. Badacze są oczywiście zainteresowani zaawansowanymi i subtelnymi funkcjami, natomiast użytkownicy, którzy nie mają odpowiedniej wiedzy, cenią szczegółowe przewodniki i diagramy.
Chcę zrealizować ten projekt ze względów osobistych i zawodowych. Przede wszystkim chcę w dużym stopniu wnieść swój wkład w naukę SciPy, ponieważ moje badania bardzo przyniosły korzyści. Po drugie, zbyt często w innym oprogramowaniu mam do czynienia z niewystarczającą (lub jej brakiem) dokumentacji. Zawsze zastanawiam się, o ile szybciej (jeśli to wszystko) użytkownicy nauczą się korzystać z kodu, jeśli mają im szczegółowy przewodnik.
Cele:
Zamierzam ulepszyć istniejącą dokumentację SciPy pod względem treści i grafiki. Najważniejszą cechą mojego podejścia do tego problemu jest wdrożenie i analiza ankiety użytkowników, czyli zwięzłej ankiety przeprowadzonej online, która umożliwia różnym użytkownikom wyrażenie swoich potrzeb dotyczących dokumentacji. Głęboko uważam, że ich opinie powinny być źródłem inspiracji (jak inaczej możemy utworzyć bardziej przyjazną dla użytkownika dokumentację?).
Jeśli chodzi o realizację projektu, pierwszy etap będzie polegał na zaprojektowaniu i analizie ankiety wśród użytkowników, a także omówieniu kilku kwestii stylistycznych, które pojawiły się w bieżącej dokumentacji. Na przykład: brak spójności (przykład: dwuwymiarowe tablice występujące równolegle z tablicami dwuwymiarowymi), zawiłe zdania wymagające przeredagowania lub brak kolejności alfabetycznej na niektórych podstronach. W drugim etapie skupimy się na wprowadzeniu graficznych przewodników zawierających hiperlinki do odpowiednich tematów (na podstawie wyników ankiety i innych próśb społeczności). W dłuższej perspektywie chcę tworzyć satysfakcjonującą dokumentację dostosowaną do różnych użytkowników. Będę też dążyć do tego, aby samouczki były bardziej spójne pod względem lingwistycznym i strukturalnym. Na koniec chcę też tworzyć nowe samouczki (na podstawie aktualnych potrzeb społeczności).
Ankieta dla użytkowników:
Jeśli chodzi o ankietę użytkowników, proponuję skorzystanie z Formularzy Google z kilku powodów. Przede wszystkim Formularze Google są bezpłatne i oferują nieograniczoną funkcjonalność (pod względem liczby respondentów, pytań itp.), atrakcyjnej formy wizualnej, najbardziej przydatnych opcji ankiety (np. dostosowywana skala liniowa, pola wyboru i możliwości wielokrotnego wyboru), a co najważniejsze – wyniki można łatwo eksportować do analizy statystycznej. Z przeprowadzonych badań wynika, że obecnie najlepszym bezpłatnym narzędziem do przeprowadzania ankiet są Formularze Google. Mówiąc mniej poważnie, byłby miłym gestem wykorzystania usługi Google w ramach inicjatywy Google.
Przygotowałem(-am) ankietę wstępną z przykładowymi pytaniami (dostępna jest tutaj: https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Ostateczna liczba pytań powinna mieścić się w przedziale od 10 do 15 pytań. Aby uzyskać konkretne wyniki, stosuj głównie pytania jednokrotnego wyboru, skalę liniową i kilka pól wyboru. Skala liniowa nie powinna jednak przypominać pełnego spektrum (powoduje to tylko dezorientację, a wyniki mogą zaciekawić). Powinno być maksymalnie 2 pytania otwarte. W przeciwnym razie wyniki będą rozproszone i ogólnie nieprzydatne. Przewiduję, że nawet bardzo duża liczba odpowiedzi nie będzie problematyczna, ponieważ dane można łatwo eksportować i analizować automatycznie za pomocą oprogramowania statystycznego. Zakładając, że liczba odpowiedzi jest w rzeczywistości bardzo duża, analiza pytań otwartych może być czasochłonna, ale sądzę, że nie będzie przytłaczająca. Przeciętny użytkownik raczej nie napisze wypracowania na temat stanu dokumentacji. W najgorszym razie niektóre odpowiedzi można po prostu zapisać na potrzeby przyszłej analizy.
Przewodniki graficzne:
Moja wizja przewodników graficznych (które mają pełnić rolę narzędzi nawigacyjnych) opiera się na popularnym założeniu, że (większość) ludzi lepiej sobie radzi z przetwarzaniem prostych struktur wizualnych, a nie tylko informacji tekstowych. Poza tym tematyczny diagram z liniami łączącymi podobne zainteresowania jest niewątpliwie bardzo przydatnym narzędziem dla mniej doświadczonych użytkowników (i nie tylko).
Jeśli chodzi o szczegóły wdrożenia, proponuję skorzystać z pakietu TikZ. Przede wszystkim jest to zaawansowane narzędzie, które prawdopodobnie nie zostanie wkrótce wycofane. Oferuje również wysokiej jakości dane wyjściowe, ma solidną dokumentację i jest często poruszanym tematem w TeX StackExchange i na innych forach popularnych narzędzi. Przede wszystkim jednak wydaje się, że integracja pliku TikZ (a dokładniej znajdujących się w nim hiperlinków) z dokumentacją HTML nie stwarza istotnych problemów ze względu na istnienie różnych pakietów i poprawek umożliwiających umieszczenie zdjęcia TikZ w kodzie HTML (np. TeX4ht).
Kwestię przyszłej obsługi przewodników w SciPy można łatwo rozwiązać, używając na przykład Overleaf (ułatwia współpracę i oferuje błyskawiczny podgląd) oraz wstępnie zdefiniowane szablony, które udostępnię. Zasadniczo przewodniki graficzne prawdopodobnie nie różnią się od siebie znacząco. Struktura, paleta kolorów i kształty są mniej lub bardziej niezmienne, więc kolejne kształtowanie i dalsze dostosowywanie nie będą problemem.
(Pełna wersja propozycji jest dostępna w udostępnionym folderze GSoD).