Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- Matplotlib
- Pisarz techniczny:
- Jeromew
- Nazwa projektu:
- Rozwijanie ścieżek wejścia Matplotlib
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Wstęp
Propozycja projektu Matplotlib na tegoroczny sezon korzystania z Dokumentów Google polega na stworzeniu treści, które ułatwią przedstawienie Matplotlib nowym użytkownikom. Na potrzeby opracowywania ścieżek wejścia Matplotlib proponuję inne podejście niż w przypadku bieżącej dokumentacji. Jestem nowym redaktorem technicznym w branży, ale mam doświadczenie w dziedzinach powiązanych z edukacją. Pisarstwo techniczne i edukacja mają duże podobieństwo do tworzenia empatii i umożliwiających użytkownikom wykonywanie zadań przy użyciu dostępnych zasobów.
W tym kontekście dokumentacja Matplotlib mogłaby poprawić empatię nowych użytkowników. Duża część materiału składa się obecnie z losowych danych i wizualizacji bez etykiet. Świetnie nadają się do szybkiego prezentowania elementów graficznych i funkcji Matplotlib. Jednak w przypadku użycia przez osoby, które dopiero zaczynają korzystać z Matplotlib, przechodzenie transformacji danych w materiały wizualne może być trudne.
Rozwiązaniem tej przeszkody jest kontekst w podejściem pomocniczym. Opisując procedurę przez pryzmat rzeczywistego przykładu, pokazujemy środowisko, w którym działa użytkownik. Pozwala to poprawić relację między dokumentacją a użytkownikiem w zakresie osiągnięcia celu lub oczekiwania związanego z wykonaniem zadania.
Użytkownik ma określony cel. Na przykład badacz danych w firmie obuwniczej musi przedstawić dane klientów zespołowi, aby zilustrować trendy zakupowe na przestrzeni czasu. W takiej sytuacji użytkownik musi nauczyć się poruszać się po Matplotlib i korzystać z narzędzi dostępnych w bibliotece, by wykonać zadanie.
Dzięki dodatkowemu kontekstowi dla dokumentacji nowy użytkownik może łatwiej identyfikować się z tematem. Uzyskany cel użytkownika jest taki sam jak w dokumentacji. Mam nadzieję, że uda mi się osiągnąć wizję, którą główny programista Tom Caswell omówił w wywiadzie w 2017 roku jako „możliwość pisania kogoś, kto potrafi pisać i okazuje empatię użytkownikom, aby napisać 200-stronicową książkę „Wprowadzenie do Matplotlib” i uczynić ją główną pozycją w dokumentacji”.
Alternatywne podejście do pisania poglądowego
Obecna dokumentacja przedstawia funkcje Matplotlib, czyli to, co użytkownik może robić w bibliotece. Na przykład w przypadku samouczka często stosuje się wzór, który nie obejmuje wyjaśnienia metody bazowej.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
Często w przypadku dokumentacji i pomocy dotyczącej programowania zalecamy użytkownikowi samodzielne uruchomienie kodu, aby zrozumieć, co się dzieje. Chociaż nastawienie do programowania pozwala użytkownikowi lepiej zrozumieć dany temat, krzywa uczenia się transformacji nie zawiera zbyt wielu materiałów pomocniczych. Ze względu na ograniczoną dokumentację może być trudne.
Dostarczenie dodatkowych diagramów, obrazów i innych materiałów wizualnych pomoże stworzyć nowe możliwości nauki. Poniższa struktura również może być szablonem dla nowych treści. Dodanie obrazów lub grafik nietekstowych przyniesie korzyści takie jak objaśnienia i oznaczenia trenerów. Czasami trudniej jest nawigować po obrazach, nie informując o tym, jak i gdzie kod jest przekształcany w wyniki. Uważam, że brakuje istotnego elementu wizualnego, który umożliwiłby lepsze zrozumienie poruszanych tematów.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
To alternatywne podejście, jakim jest wykorzystanie tekstu ekspozycyjnego w dokumentacji, ma ogromny potencjał. Gdy użytkownicy widzą różne koncepcje przekształceń, mogą lepiej identyfikować podstawowe strategie tworzenia wizualizacji danych. Wiedza ta może pomóc użytkownikom w tworzeniu innowacji i wykorzystywaniu funkcji przedstawionych na przykładach w realistycznych przypadkach użycia.
Ponieważ Matplotlib zyskuje na popularności, o reputacji tej biblioteki świadczy spójność w zakresie jej łatwości użytkowania i przystępności. Te cechy pozwalają wykazać wzorce i typowe strategie, które można znaleźć nie tylko w kodzie, ale również w dokumentacji. Jeśli programowanie w Matplotlib jest proste i standardowe, co widać w jego rosnącym wykorzystaniu i rozwijaniu zasobów, może się to odbywać również w przypadku dokumentacji technicznej.
Kiedy użytkownicy napotykają problemy, często w celu ich rozwiązania korzystają z wyszukiwarki. Zamiast polegać na wyszukiwarce jako głównej metodzie nawigacji, lepiej jest, gdy użytkownicy stworzą własny program nauczania w dokumentacji. W takiej sytuacji użytkownik szuka rozwiązania swojego problemu, a gdy natrafi na inny problem lub będzie chciał uzyskać dodatkowe informacje, korzysta z osadzonych i wyczerpujących linków.
Obejmuje to architekturę oddolną w systemie organizacyjnym. W stworzeniu rozbudowanej sieci na potrzeby każdego tematu w Matplotlibu może pomóc bogata sieć linków do podobnych zainteresowań oraz tematów informacyjnych. W całej tej sieci użytkownik z większym prawdopodobieństwem będzie korzystać z dokumentacji, przechodząc do danego tematu i zgłębiając związane z nim informacje.
Przeszkody
W projektach zawsze wiążą się jakieś wyzwania, które są tak kompleksowe i szczegółowe. Jako nowicjusz techniczny w branży mam ograniczone doświadczenie w pisaniu dokumentacji dotyczącej Sphinx i ReST. Jestem też początkującym użytkownikiem Matplotlib i Git. Wykorzystanie tych 4 systemów do współpracy i badania może trochę potrwać. Muszę zarezerwować trochę czasu na etapie budowania więzi ze społecznością i wcześniej, aby stworzyć niezbędną bazę dla początkujących. W tym czasie, jeśli mam problemy z pojęciami i podstawowymi zasadami, muszę skontaktować się ze społecznością, aby uzyskać dodatkową pomoc.
Koordynowanie działań w ramach współpracy w różnych strefach czasowych i na platformach online również wymaga pewnego dostosowania. Istnieje wiele sposobów komunikacji, z których korzystają ludzie z całej branży. Dlatego ważne jest, aby mieć pewność, że jestem przystępny we wszystkich mediach. Będę jasno i przejrzyście przedstawiać moje różne oczekiwania. Dopiero zaczynam z podejmowaniem takich działań w branży, ale chcę zmusić się do odpowiedzialności i otwarcia się na opinie i krytykę. Uważam, że te cechy są cenne bez względu na dziedzinę.
Poza tym zwiększenie liczby testów użyteczności to jeden z elementów dokumentacji, który moim zdaniem przyniósłby korzyści w przypadku ścieżek wejścia Matplotlib. Przeprowadzanie ankiet pod kątem użyteczności w odniesieniu do treści ma na celu opracowanie profilu użytkownika, tj. profili użytkownika. Informacje dotyczące wrażeń użytkownika, branży i rozwiązywania problemów są bardzo cenne. Elementy te pomagają w określeniu języka procedury. Treści, które tworzą czytelnicy na ich poziomie, uczą się już nie tylko o charakterze instruktażowym.
Duże problemy często wiążą się z nieprzerwanym testowaniem użyteczności. Zbyt często zdarza się, że pojedyncze testy przeprowadzane są w ogóle podczas tworzenia treści (o ile w ogóle nie są przeprowadzane). Regularne testy użyteczności pomagają kształtować przekaz dotyczący treści. Może uda mi się ustalić harmonogram lub zorganizować cykliczne testy użyteczności ze społecznością Matplotlib?
Podsumowanie
W wolnym czasie mam trochę doświadczenia w korzystaniu z Pythona oraz Matplotlib. Ilość, którą udało mi się zdobyć w ciągu ostatnich kilku miesięcy, opierała się na obecnej dokumentacji i w ramach własnej ciekawości. W tamtym czasie miałam też sporo filmów i mentorów. Mam jeszcze sporo do nauczenia się i jeszcze więcej możliwości, ponieważ opracowuję własny program nauczania, który mnie interesuje.
Po zapoznaniu się z pomysłami Matplotlib i społeczności na GSoD uważam, że byłoby to wspaniałą, rozwojową okazję, aby doskonalić swoje umiejętności pisarza technicznego i uczyć się od zza kulis tej platformy. Sądzę, że projekt w Matplotlib ma sens i jest czymś, co fascynuje mnie ideologię.
Przygotowując się do zmian w przewodniku użytkowania, chciałem pomóc użytkownikom w wykonywaniu oczekiwanych przez nich zadań bez przytłoczenia dostępnych funkcji. Uważam, że najlepsza dokumentacja będzie stale rozwijać się i dostosowywać do potrzeb użytkowników, a każdy użytkownik może samodzielnie znaleźć rozwiązanie.