Ta strona zawiera szczegóły projektu technicznego do pisania w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source
- Matplotlib
- Pisarz techniczny:
- jeromev
- Nazwa projektu:
- Tworzenie ścieżek wejściowych Matplotlib
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Wprowadzenie
W tym roku w ramach Google Season of Docs zespół Matplotlib proponuje tworzenie treści, które pomogą w zapoznaniu się z tą biblioteką nowym użytkownikom. W rozdziale „Developing Matplotlib Entry Paths” proponuję podejście alternatywne do obecnej dokumentacji. Jestem nowym autorem treści technicznych w tej branży, ale mam doświadczenie w edukacji i powiązanych z nią dziedzinach. Pisząc teksty techniczne i prowadząc szkolenia, należy skupić się na tworzeniu treści, które wzbudzają współczucie i umożliwiają użytkownikom realizację zadań przy użyciu udostępnionych zasobów.
W tym kontekście dokumentacja Matplotlib mogłaby zostać ulepszona, aby uwzględniała potrzeby nowych użytkowników. Obecnie większość materiałów składa się z losowych danych i wizualizacji bez etykiet. Są one doskonałe do szybkiego wyświetlania wizualizacji i funkcji Matplotlib. Jednak w przypadku osób, które dopiero zaczynają korzystać z matplotlib, przekształcanie danych w wizualizacje może być trudne.
Kontekst w ramach prezentacji sprzedażowej stanowi rozwiązanie tej przeszkody. Opisując procedurę z perspektywy prawdziwego przykładu, demonstrujemy zrozumienie środowiska, w którym pracuje użytkownik. Poprawia to relację między dokumentacją a użytkownikiem w zakresie osiągania celów lub oczekiwań związanych z wykonywaniem zadań.
Użytkownik ma spójny cel pochodzenia. Na przykład analityk danych w firmie sprzedającej obuwie musi przedstawić dane o klientach zespołowi, aby zilustrować trendy zakupowe na przestrzeni czasu. W takiej sytuacji użytkownik musi nauczyć się poruszać po Matplotlib i korzystać z narzędzi w bibliotece, aby wykonać dane zadanie.
Dzięki dodatkowemu kontekstowi w dokumentacji nowy użytkownik może lepiej zrozumieć dany temat. Użytkownik może uzyskać dostęp do informacji na temat celu równolegle z dokumentacją. Mam nadzieję, że uda mi się zrealizować wizję, którą nasz główny programista Tom Caswell przedstawił w wywiadzie z 2017 r.: „Musi być to osoba, która potrafi pisać i ma empatię dla użytkowników, aby przejść przez 200-stronicową książkę „Intro to Matplotlib” i stworzyć na jej podstawie główną dokumentację”.
Alternatywne podejście do pisania ekspozycji
Obecna dokumentacja prezentuje funkcje Matplotlib, czyli to, co użytkownik może zrobić z tą biblioteką. Na przykład samouczek często nie zawiera wyjaśnienia metody.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
W dokumentacji i wsparciu często zaleca się, aby użytkownik samodzielnie uruchomił kod, aby zrozumieć, co się dzieje. Chociaż programowanie wymaga od użytkowników zrozumienia pewnych zagadnień, ścieżka uczenia się związanych z nimi zagadnień zawiera niewiele treści pomocniczych. Ze względu na ograniczoną dokumentację może to być nie lada wyzwaniem.
Dodatkowe diagramy, obrazy i inne materiały wizualne pomogą stworzyć nowe możliwości nauki. Struktura poniżej może też służyć jako szablon nowych treści. Dodawanie obrazów lub grafik bez tekstu może być przydatne w przypadku funkcji takich jak ramki i wskaźniki. Czasami trudno jest się poruszać po obrazach, jeśli nie ma informacji o tym, jak i gdzie kod jest przekształcany w wynik. Brakuje mi mocnego elementu wizualnego, który ułatwiałby zrozumienie tematów.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
To alternatywne podejście do tworzenia dokumentacji ma ogromny potencjał. Dzięki temu, że użytkownicy będą mogli zobaczyć różne koncepcje przekształcania danych, będą mogli lepiej zrozumieć strategie tworzenia wizualizacji danych. Wiedza ta może pomóc użytkownikom w tworzeniu innowacyjnych rozwiązań i wykorzystaniu funkcji przedstawionych na przykładach opartych na realistycznych przykładach.
Popularność biblioteki Matplotlib rośnie, a jej łatwość użycia i przystępność są dowodem na jej renomę. Te cechy umożliwiają demonstrowanie wzorców i popularnych strategii, które mogą się pojawiać nie tylko w kodzie, ale też w dokumentacji. Jeśli Matplotlib jest prosty i standardowy dla użytkowników, co widać po rosnącym wykorzystaniu i rozszerzaniu zasobów, może być też przydatny w dokumentacji technicznej.
Gdy użytkownicy napotykają problemy, często do ich rozwiązywania używa się wyszukiwarka. Zamiast polegać na wyszukiwaniu jako podstawowej metodzie nawigacji, możesz zachęcić użytkowników do tworzenia własnych programów nauczania w dokumentacji. W tym sensie użytkownik szuka rozwiązania swojego problemu, a gdy napotka inny problem lub będzie potrzebować dodatkowych informacji, skorzysta z dostępnych w całym tekście linków.
W tym przypadku w systemie organizacyjnym zastosowano architekturę od dołu do góry. W przypadku każdego tematu w Matplotlib można zbudować solidną sieć, korzystając z bogatej sieci linków do tematów pokrewnych oraz tematów informacyjnych. W tej sieci użytkownik chętniej będzie korzystać z dokumentacji, gdy będzie przechodzić do interesującego go tematu i poznawać więcej informacji na ten temat.
Przeszkody
W przypadku tak obszernego i szczegółowego projektu zawsze pojawiają się problemy. Jestem nowym autorem dokumentacji technicznej w branży i mam ograniczone doświadczenie w pisaniu dokumentów w Sphinx i ReST. Jestem też początkującym użytkownikiem Matplotlib i Git. Zapoznanie się z tymi 4 systemami i nauczenie się ich używania do współpracy i prowadzenia badań zajmie trochę czasu. W fazie budowania więzi ze społecznością i wcześniej będę musiała delegować czas, aby stworzyć niezbędne podstawy ścieżek na poziomie podstawowym. Jeśli w tym czasie będę mieć problemy z koncepcjami i podstadami, będę musiał zwrócić się o pomoc do społeczności.
Koordynowanie działań w ramach współpracy w różnych strefach czasowych i na platformach internetowych również wymaga pewnych zmian. Użytkownicy w całej branży mogą korzystać z różnych form komunikacji, dlatego muszę zadbać o dostępność i możliwość kontaktu w każdej z nich. Będę jawnie nadawać priorytet różnym oczekiwaniom. Chociaż dopiero zaczynam wykonywać tego typu zadania w tej branży, staram się być odpowiedzialna i otwarta na opinie oraz krytykę. Uważam, że te cechy są cenne w każdej dziedzinie.
Ponadto zwiększenie testów użyteczności to sekcja dokumentacji, która moim zdaniem przydałaby się w przypadku ścieżek wejścia Matplotlib. Przeprowadzanie ankiet dotyczących użyteczności treści służy do tworzenia profilu użytkownika, czyli persony. Cenne są informacje takie jak doświadczenie użytkownika, branża i historia rozwiązywania problemów. Te elementy pomagają w określaniu języka procedury. Gdy teksty są dopasowane do poziomu odbiorców, treści przestają być tylko instruktażowe.
Największe problemy często pojawiają się podczas tworzenia ciągłego procesu testowania użyteczności. Zbyt często zdarza się, że podczas tworzenia treści przeprowadza się tylko jedno testowanie, jeśli w ogóle. Regularne testy użyteczności pomagają w rozwijaniu narracji treści. Chciałbym skonfigurować harmonogram lub przeprowadzać cykliczne testy użyteczności z pomocą społeczności Matplotlib.
Podsumowanie
W wolnym czasie mam niewielkie doświadczenie w używaniu Pythona i Matplotlib. W ciągu ostatnich kilku miesięcy nauczyłem się bardzo dużo, korzystając z aktualnej dokumentacji i własnej ciekawości. W tym czasie obejrzałem też kilka filmów i miałem kilku mentorów. Nadal mam wiele do nauczenia się i jeszcze więcej możliwości do poprawy, ponieważ tworzę własny program nauczania programowania, który mnie interesuje.
Po zapoznaniu się z pomysłami Matplotlib i społeczności na temat GSoD uważam, że będzie to świetna okazja do rozwijania się jako autorka tekstów technicznych i uczenia się od osób, które stoją za kulisami. Uważam, że ten projekt z Matplotlib jest wartościowy i jest dla mnie pasjonatem w ideologii.
Jako redaktor ds. technicznych staram się pomagać użytkownikom w wykonywaniu potrzebnych im zadań, tak aby nie przytłoczyć ich dostępnymi funkcjami. Uważam, że najlepsza dokumentacja stale się powiększa i dostosowuje do użytkowników, aby każdy mógł znaleźć własne rozwiązania.