Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- SciPy
- Pisarz techniczny:
- mkg33
- Nazwa projektu:
- Dokumentacja przygotowana dla użytkowników i dokładna restrukturyzacja
- 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. Oczywistym jest, że badacz jest najbardziej zainteresowany zaawansowanymi i subtelnymi funkcjami, natomiast użytkownicy, którzy nie mają odpowiedniej wiedzy, cenią szczegółowe przewodniki i schematy.
Zastanawiam się nad realizacją tego projektu z powodów osobistych i zawodowych. Przede wszystkim chcę w dużym stopniu wnieść swój wkład w SciPy, ponieważ moje badania bardzo pomogły mi. Po drugie, zbyt często w innym oprogramowaniu mam do czynienia z niewystarczającą (lub brakiem) dokumentacji i zawsze zastanawiam się, o ile szybciej (o ile w ogóle) użytkownicy będą mogli nauczyć się korzystać z kodu, jeśli mają do nich dostęp dzięki dokładnym wskazówkom.
Cele:
Staram się 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ła ankieta przeprowadzona online, dzięki której różni użytkownicy mogą wyrazić swoje potrzeby dotyczące dokumentacji. 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 polega na zaprojektowaniu i analizie ankiety wśród użytkowników oraz o zapoznaniu się z kilkoma problemami stylistycznymi zauważonymi w obecnej dokumentacji. Na przykład brak spójności (np. dwuwymiarowe tablice występujące obok tablic dwuwymiarowych), skomplikowane zdania, które należy przepisać, 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). Zamierzam w przyszłości tworzyć zadowalającą dokumentację stworzoną z myślą o różnych użytkownikach. Postaram się także, aby samouczki były bardziej spójne pod względem językowym i strukturalnym. Chciałabym też napisać nowe samouczki (na podstawie aktualnych potrzeb społeczności).
Ankieta dla użytkowników:
Jeśli chodzi o ankietę dla użytkowników, proponuję skorzystać z Formularzy Google z kilku powodów. Przede wszystkim Formularze Google są bezpłatne i oferują nieograniczoną funkcjonalność (w zakresie liczby respondentów, liczby pytań itp.), atrakcyjnej formy wizualnej, najbardziej przydatnych opcji ankiety (np. dostosowywana skala liniowa, pola wyboru i wielokrotnego wyboru), a co najważniejsze, wyniki można łatwo eksportować do analizy statystycznej. Z badań online wynika, że Formularze Google są, przynajmniej na razie, najlepszym bezpłatnym narzędziem do przeprowadzania ankiet. Mówiąc mniej poważnie, wykorzystanie usługi Google w ramach inicjatywy Google to miły gest.
Przygotowałem(-am) wstępną ankietę z przykładowymi pytaniami (można ją znaleźć tutaj: https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Ostateczna liczba pytań powinna wynosić od 10 do 15. W celu uzyskania konkretnych wyników proponujemy użyć głównie pytań jednokrotnego wyboru, skali liniowej i kilku pól wyboru. Skala liniowa nie powinna przypominać pełnego spektrum (powoduje to tylko dezorientację, a wyniki prawdopodobnie będą miały negatywny wpływ na dużą rozproszenie). Możesz dodać maksymalnie 2 pytania otwarte. W przeciwnym razie wyniki będą bardzo 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. Przy założeniu, że liczba odpowiedzi jest rzeczywiście bardzo wysoka, analiza pytań otwartych może być trochę czasochłonna, ale domyślam się, ż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 mogą być po prostu przechowywane na potrzeby przyszłej analizy.
Przewodniki graficzne:
Moja wizja przewodników graficznych (które mają służyć za narzędzia nawigacyjne) opiera się na popularnym założeniu, że (większość) ludzi lepiej radzi sobie z przetwarzaniem prostych struktur wizualnych, a nie tylko informacji tekstowych. Dodatkowo tematyczny diagram z liniami łączącymi podobne tematy jest niewątpliwie bardzo przydatnym narzędziem dla mniej doświadczonych użytkowników (i nie tylko).
Jeśli chodzi o szczegóły implementacji, 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 tematem wiadomości na temat TeX StackExchange i innych popularnych forów. Przede wszystkim integracja pliku TikZ (a konkretnie zawarte w nim liczne hiperlinki) z dokumentacją HTML nie stwarza istotnych problemów ze względu na istnienie różnych pakietów i poprawek umożliwiających umieszczanie zdjęcia TikZ w kodzie HTML (na przykład TeX4ht).
Kwestię przyszłej obsługi przewodników w SciPy można łatwo rozwiązać, używając np. Overleaf (ułatwia współpracę i udostępnia natychmiastowy podgląd) oraz wstępnie zdefiniowanych szablonów, które udostępnię. Zasadniczo przewodniki graficzne najprawdopodobniej nie różnią się od siebie znacząco. Struktura, paleta kolorów i kształty są mniej więcej niezmiennie niezmienne, więc kolejne kształty i dostosowywanie nie będą problemem.
(Pełna wersja propozycji jest dostępna w udostępnionym folderze GSoD).