Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.
Podsumowanie projektu
- Organizacja open source:
- SciPy
- Specjalista ds. technicznych:
- mkg33
- Nazwa projektu:
- Dokumentacja zorientowana na użytkownika i gruntowne przestrukturyzowanie
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Motywacja:
Zamierzam przeprowadzić refaktoryzację istniejącej dokumentacji, aby była ona łatwo dostępna dla użytkowników o różnych potrzebach. Jest oczywiste, że badacz jest najprawdopodobniej zainteresowany funkcjami zaawansowanymi i subtelnymi, podczas gdy użytkownikom bez wcześniejszego doświadczenia ceni się szczegółowe przewodniki i schematy.
Chcę kontynuować ten projekt z powodów osobistych i zawodowych: po pierwsze, chcę w znacznym stopniu przyczynić się do rozwoju SciPy, ponieważ przyniósł ono wiele korzyści w moim własnym badaniu. Po drugie, w innym oprogramowaniu zbyt często spotykam się z niewystarczającą (lub wcale nieistniejącą) dokumentacją i zawsze zastanawiam się, jak dużo szybciej (jeśli w ogóle) użytkownicy mogliby nauczyć się korzystania z kodu, gdyby otrzymali dokładny przewodnik.
Cele:
Celem jest ulepszenie istniejącej dokumentacji SciPy pod względem treści i grafiki. Najważniejszym elementem mojego podejścia do tego problemu jest wdrożenie i przeanalizowanie ankiety dla użytkowników, czyli krótkiego ankiety przeprowadzonego online, który umożliwia różnym użytkownikom wyrażenie swoich potrzeb dotyczących dokumentacji. Jestem przekonana, że ich opinie powinny być źródłem inspiracji (w jaki inny sposób moglibyśmy stworzyć dokumentację bardziej przyjazną użytkownikom?).
W przypadku realizacji samego projektu pierwsza faza obejmie zaprojektowanie i przeanalizowanie ankiety dla użytkowników oraz rozwiązanie kilku problemów ze stylistyką, które zauważyłem w obecnej dokumentacji. Na przykład brak spójności (np. dwuwymiarowe tablice występujące obok dwuwymiarowych tablic), zawiłe zdania, które należy przepisać, lub brak kolejności alfabetycznej na niektórych podstronach. Druga faza będzie polegać na wprowadzeniu przewodników graficznych zawierających hiperlinki do odpowiednich tematów (na podstawie wyników ankiety i innych próśb społeczności). Chcę w długim okresie uzyskać satysfakcjonującą dokumentację dostosowaną do różnych typów użytkowników. Postaram się też, aby samouczki były bardziej spójne pod względem językowym i struktury. Na koniec staram się napisać nowe samouczki (uwzględniając aktualne potrzeby społeczności).
Ankieta dla użytkowników:
W przypadku ankiety dla użytkowników proponuję użycie Formularzy Google z kilku powodów. Po pierwsze, Formularze Google są bezpłatne i oferują nieograniczoną funkcjonalność (w zakresie liczby respondentów, pytań itp.), mają atrakcyjną formę wizualną, najprzydatniejsze opcje ankiet (np. dostosowywaną skalę liniową, pola wyboru i pytania jednokrotnego wyboru), a co najważniejsze, wyniki można łatwo eksportować na potrzeby analizy statystycznej. Na podstawie badań online wygląda na to, że Formularze Google są, przynajmniej na razie, najlepszym bezpłatnym narzędziem do przeprowadzania ankiet. W mniej poważnym tonie: warto używać usług Google w ramach inicjatywy prowadzonej przez Google.
Mam utworzoną wstępną ankietę z przykładowymi pytaniami (jest ona dostępna tutaj: https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). W wersji końcowej powinno być od 10 do 15 pytań. Aby uzyskać konkretne wyniki, zalecamy używanie głównie pytań jednokrotnego wyboru, skali liniowej i kilku pól wyboru. Skala liniowa nie powinna jednak przypominać pełnego spektrum (powoduje to tylko zamieszanie, a wyniki mogą być bardzo rozproszone). Powinny być maksymalnie 2 pytania otwarte, ponieważ w przeciwnym razie wyniki będą bardzo rozproszone i nieprzydatne. Sądzę, że nawet bardzo duża liczba odpowiedzi nie będzie problemem, ponieważ dane można łatwo wyeksportować i automatycznie analizować za pomocą oprogramowania statystycznego. Zakładając, że liczba odpowiedzi jest rzeczywiście bardzo wysoka, analiza pytań otwartych może trochę zająć czasu, ale nie powinno to być przytłaczające. Przecież przeciętny użytkownik raczej nie napisze wypracowania na temat stanu dokumentacji. W najgorszym przypadku 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ć jako narzędzia nawigacyjne) opiera się na popularnym założeniu, że (większość) ludzi lepiej radzi sobie z przetwarzaniem prostych struktur wizualnych niż z informacjami wyłącznie tekstowymi. Poza tym diagram tematyczny z liniami łączącymi podobne tematy zainteresowań jest bez wątpienia bardzo cennym zasobem dla mniej doświadczonych użytkowników (i nie tylko).
Jeśli chodzi o szczegóły implementacji, proponuję użyć pakietu TikZ. Przede wszystkim jest to zaawansowane narzędzie i wygląda na to, że wkrótce zostanie wycofane. Zapewnia też wysoką jakość wyników, zawiera naprawdę rzetelną dokumentację i jest częstym tematem na TeX StackExchange i innych forach mainstreamowych. Co najważniejsze, integracja pliku TikZ (a dokładnie zawarte w nim hiperlinki) z dokumentacją HTML wydaje się nie stwarzać poważnych problemów ze względu na istnienie różnych pakietów i poprawki umożliwiające umieszczanie grafiki z TikZ w kodzie HTML (na przykład TeX4ht).
Odpowiedź na pytanie o obsługę przewodników w aplikacji SciPy można łatwo rozwiązać, używając na przykład Overleaf (ułatwia współpracę, oferuje natychmiastowy podgląd) oraz wstępnie zdefiniowanych szablonów, które dostarczę. Zasadniczo przewodniki graficzne nie różnią się od siebie znacząco. Struktura, paleta kolorów i kształty będą mniej lub bardziej niezmienne, więc późniejsze zmiany kształtu i dalsze dostosowywanie nie będą problemem.
(Zobacz pełną wersję propozycji – znajdziesz w udostępnionym folderze GSOD).