Ta strona zawiera szczegóły projektu technicznego do pisania w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- NumPy
- Specjalista ds. technicznych:
- cooperrc
- Nazwa projektu:
- Dokumentacja NumPy dla społeczności
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Wprowadzenie
NumPy to czysta i szybka biblioteka oprogramowania typu open source, która umożliwia wykonywanie obliczeń na tablicach. Jest to fundamentalny pakiet stosu SciPy dla obliczeń naukowych [1]. Ponad 370 tysięcy projektów korzysta z niego do efektywnego przetwarzania tablic [2]. Użytkownikom aplikacji NumPy wyświetla się nowa witryna z aplikacjami i studiami przypadków [1]. Gdy nowy użytkownik znajdzie stronę dokumentacji, zobaczy wiele linków „Zacznij tutaj” i wprowadzających samouczków, które mogą przytłoczyć początkującego, np. NumPy Basics/byte-swapping. Zacząłem używać NumPy 10 lat temu, gdy byłem na studiach podyplomowych. Aby uniknąć czytania dokumentacji NumPy, musiałem połączyć ze sobą posty z blogów, notatki z wykładów i odpowiedzi na StackExchange. Obecnie w StackExchange jest ponad 360 tys. rozmów dotyczących NumPy. Wydaje mi się, że inni użytkownicy z podobnymi drogami do sukcesu w NumPy mogli osiągnąć sukces. Elementy składowe narzędzi edukacyjnych to komunikacja i społeczność [4]. Dokumentacja musi tworzyć społeczność, która odzwierciedla zamierzone cele projektu. Dokumentacja powinna być spójna i jasna dla nowego użytkownika. Samouczki powinny zawierać proste instrukcje, które ułatwią nowym użytkownikom zapoznanie się z biblioteką [3]. Dokumentacja powinna powitać nowego użytkownika w społeczności NumPy. Struktura, tempo i autorzy dokumentacji muszą zapewnić miejsce, które umożliwi zwiedzanie i komunikację. Ta propozycja pozwoli uporządkować i uzupełnić luki w obecnej dokumentacji NumPy, aby nowi użytkownicy mogli się uczyć i dołączyć do społeczności.
Wiedza, którą użytkownicy przekazują, jest zdobywana przez testowanie i eksperymentowanie [4,5]. Wiedza zależy od metody testowania i oceny. Treści, które zawierają jasne cele i sposoby ich realizacji, pozwalają użytkownikom testować i ocenić nowe pomysły i metody. Społeczność może rozbudowywać bazę wiedzy i rozszerzać umiejętności, fakty oraz wnioski. Sekcja „Jak to zrobić” przynosi podwójne korzyści. Po pierwsze, zarówno nowi, jak i doświadczeni użytkownicy mają do dyspozycji zestaw jasnych celów, które mogą testować i wykorzystywać w eksperymentach. Po drugie, potencjalni autorzy dokumentacji mają miejsce na przedstawienie swoich celów, metod i rozwiązań. Sekcja „Jak to zrobić” powstała, aby ułatwić dostęp do dokumentacji NumPy nowym użytkownikom i potencjalnym współtwórcom. Aktualna wiedza
John Dewey twierdził, że podstawą nauki jest autentyczne doświadczenie [4]. Społeczność NumPy ma ogromne doświadczenie, którym może się dzielić z innymi użytkownikami. Edukacja opiera się na społeczności i komunikacji. Uporządkowana strona dokumentacji ułatwia nowym użytkownikom korzystanie z NumPy. Tworzy też uporządkowany szablon, który umożliwia potencjalnym współtwórcom przekazywanie informacji o swoich doświadczeniach z NumPy.
Dokumentację oprogramowania można podzielić na 4 kategorie [3]: samouczek, instrukcje, wyjaśnienia i informacje. Dokumentacja NumPy zawiera szereg dokumentów w obszarze samouczka, które łączą w sobie objaśnienia z treścią instrukcji. W tym miejscu należy skupić się na edukacji użytkowników i stosować łatwe do powtórzenia kroki, aby przekazać pomysły. Poradniki oferują więcej procedur zorientowanych na cel, które użytkownicy mogą stosować w rzeczywistych zastosowaniach. Pole wyjaśnienia zawiera szczegółowe informacje w postaci napisów w każdej funkcji. Obecne sekcje samouczków i instrukcji nie są wyraźnie od siebie odseparowane i czasami wchodzą w obszar wyjaśnień i informacji. Jest świetny samouczek dla „całkowicie początkujących” i bardzo przydatna dla użytkowników Matlaba dokumentacja dotycząca tworzenia kodu NumPy, która znajduje się w sekcji „NumPy dla użytkowników Matlaba”. Wyraźne wyodrębnienie tych 4 przestrzeni ułatwia zrozumienie dokumentacji.
Brak informacji w bazie wiedzy/niezaspokojona potrzeba
Obecna dokumentacja obejmuje wiele niezbędnych tematów, ale nie ma w niej wyraźnego rozróżnienia między samouczkami, instrukcjami, wyjaśnieniami i informacjami. Może to wprowadzać w błąd potencjalnych współtwórców. Nowi użytkownicy mogą być przytłomieni wyjaśnieniami i materiałami referencyjnymi w sekcji samouczka, a potencjalni autorzy mogą napotkać trudności w dodawaniu treści. Proponuję bardziej przejrzysty układ dla nowych użytkowników i potencjalnych autorów dokumentacji, a także logiczny przepływ dokumentacji i zarządzanie żądaniami pull dotyczącymi dokumentów instruktażowych przesłanych przez nowych autorów. Moim długoterminowym celem jest zbudowanie społeczności osób zajmujących się dokumentacją, aby uczenie się z materiałów było procesem opartym na dzieleniu się wiedzą i przekazywaniu wiedzy. Ten model dokumentacji pozwoli nowym użytkownikom i potencjalnym współtwórcom zdobyć wiedzę na podstawie rzeczywistych doświadczeń.
Uzasadnienie
Ta propozycja Google Summer of Dokumenty ma duże znaczenie dla moich celów pedagogicznych i zawodowych. Na wszystkich kursach korzystam z usług NumPy i SciPy. Obecna dokumentacja jest trudna do nawigacji dla moich uczniów. Chcę wykorzystać swoje doświadczenie w nauczaniu programowania kierunków innych niż CS, aby ułatwić porządkowanie, edytowanie i uzupełnianie luk w bieżących samouczkach. Następnie mogę używać dokumentacji jako podręcznika i materiału referencyjnego do moich kursów. Utworzyłem dziesiątki samouczków, ćwiczeń i przykładów za pomocą Pythona i
Cele szczegółowe
Mam 3 konkretne cele związane z tą propozycją Google Summer of Docs: 1. Porządkowanie bieżącej dokumentacji. Zmodyfikuj obecne samouczki (przewodnik dla początkujących, tworzenie tablic, indeksowanie, algebra liniowa i NumPy dla Matlaba), aby przenieść informacje referencyjne do sekcji Explanation Space. tworzyć materiały instruktażowe z udziałem uczniów. Każdy konkretny cel ma oczekiwany wynik w ramach oferty.
Te 3 szczególne cele mają na celu uczynić dokumentację bardziej przyjazną dla nowych użytkowników i zapewnić strukturę dla potencjalnych współtwórców. Cele te pomagają też realizować długoterminowy cel, jakim jest dalszy rozwój społeczności dokumentacyjnej NumPy. Oczekiwane wyniki
Mam 3 oczekiwane wyniki: 1. zaktualizowaną stronę dokumentacji, która wyraźnie oddziela 4 obszary: samouczki, instrukcje, wyjaśnienia i informacje referencyjne; 2. nowe samouczki dotyczące odczytu i zapisu tablic, tworzenia tablic (np.zeros, np.ones, np.block itp.) oraz operacji elementowych i algebry liniowej w NumPy; 3. wyselekcjonowane instrukcje.
Te oczekiwane wyniki pomogą nowym użytkownikom w poznawaniu dokumentów, zapewnią potencjalnym współtwórcom dokumentów jasne style i formaty, skrócą i ułatwią zapoznanie się z bieżącymi samouczkami, przenieś wyjaśnienia do osobnej sekcji, a nowi współtwórcy dokumentacji będą mogli w niewielkim stopniu dodawać materiały do sekcji z instrukcjami bez konieczności tworzenia całej dokumentacji Sphinx. Chcemy dalej rozwijać naszą społeczność nauczycieli i uczniów.
Nowi autorzy dokumentacji mogą tworzyć małe przypadki użycia dla milionów użytkowników bez konieczności tworzenia całej dokumentacji Sphinx. Chcemy dalej rozwijać naszą społeczność nauczycieli i uczniów. Proponowana dokumentacja będzie naśladować obecną dokumentację o źródle otwartym, taką jak Matplotlib czy Divio. Nowi użytkownicy i potencjalni współtwórcy łatwiej nauczą się stosować NumPy w swoich dziedzinach i programach.
Harmonogram realizacji projektu to 14–30 września 2030 r. Pierwszym krokiem jest utworzenie dokumentacji i oddzielenie treści z obecnych samouczków na samouczki, instrukcje i treści wyjaśniające. Zrobi to w ciągu pierwszych 5 tygodni projektu w ramach efektów 1 i 2, czyli odpowiednio: poprawiania witryny i tworzenia samouczników. Proponowana organizacja dokumentacji jest widoczna w poniższej Proponowanej dokumentacji.
Proponowana dokumentacja:
i.Tutorials:
- Podstawy dla początkujących (usuwanie instalacji, czy importowanie/eksportowanie danych z pandas można zastąpić funkcją numpy.loadtxt?)
- link do „What is numpy”
- link do podstawowych instrukcji instalacji
- Samouczek wprowadzający (przeznaczony do wykorzystania po samouczku dotyczącym Pythona)
- Praca z tablicami NumPy
- tworzenie tablic (np.zeros, np.ones, np.block itp.); (write: med-low priority)
- operacje element-wise (+,-,*,/) i operacje algebry liniowej (+,-,@, linalg.solve) (write:med priority)
- Odczytywanie i zapisywanie danych za pomocą Numpy (zapisywanie: wysoki priorytet)
- Indeksowanie
ii. Instrukcje:
- Algebra liniowa dla tablic n-wymiarowych (chciałbym edytować nagłówki i opisy oraz może zmienić tytuł na „Przetwarzanie obrazu za pomocą algebry liniowej Numpy”)
- link do instrukcji dotyczących numpy-tutorials (trwają prace nad tym projektem)
iii. Objaśnienie:
- Typy danych
- I/O z Numpy
- Indeksowanie
- Nadawanie
- Zamiana bajtów
- Tablice uporządkowane
- Zapisywanie kontenerów tablic niestandardowych
- podklasa ndarray
- Różne
iv. Przestrzeń referencyjna:
- Słowniczek
- Dokumentacja interfejsu Numpy API
- Numpy dla użytkowników Matlaba (tabela równoważności to świetna tabela referencyjna, ale dyskusja na temat tablic i macierzy jest rozpraszająca i wydaje się nieaktualna)
Po zakończeniu tego sezonu sugeruję następujące rezultaty:
- Ulepszona strona internetowa z dokumentacją, która wyraźnie rozdziela 4 sekcje: samouczki, instrukcje, wyjaśnienia i materiały referencyjne
- Nowe samouczki dotyczące tworzenia tablic (np.zeros, np.ones, np.block itp.), operacji elementowych (+,-,*,/) i operacji algebry liniowej (+,-,@, linalg.solve) oraz odczytywania i zapisywania danych za pomocą Numpy (wysoka priorytet).
- Zalecenie dotyczące dokumentów instruktażowych w celu zwiększenia ilości darczyńców i pomocy w realizowaniu celów społeczności w zakresie nauczania i zdobywania wiedzy.
Na każdy wynik składa się pewna liczba kroków opisanych poniżej w tabelach z Wynikami 1–3. Podczas gdy proponowana dokumentacja jest wysyłana do sprawdzenia, w ramach etapu 2. w ramach zadania 2. zostanie napisany tutorial „Czytanie i pisanie tablic” o wysokim priorytecie, który zostanie przesłany jako prośba o przechwycenie. Podczas sprawdzania poprawionej witryny i zaktualizowanego samouczka „Tablice do odczytu i zapisu” zacznę pisać samouczek tworzenia tablic przy użyciu funkcji NumPy, takich jak np.ones, np.zeros, np.diag. Pozostały czas zostanie wykorzystany na odpowiadanie na problemy związane z żądaniami pull i rozpoczęcie pisania samouczka poziomu 3: Elementarne operacje i algebra liniowa w Pythonie.
Trzecim celem jest doradzanie studentom Uniwersytetu Connecticut w tworzeniu dokumentacji w repozytorium numpy-tutorials. Przesłane samouczki lub instrukcje będą notatnikami Jupyter, które używają NumPy do rozwiązywania problemów technicznych. Do przesłania przykładowego notatnika wykorzystam notatki lub przykłady z kursu. Zalecę uczniom, aby podczas tworzenia szablonu i schematu kadrowania przestrzegali układu i struktury. Ta opcja pozwala uczniom przekazać szerszej publiczności koncepcje i rozwiązania. To świetna okazja dla uczniów, aby zaangażować się w życie społeczności NumPy i uczyć się.
Wynik 1: zaktualizowana witryna Termin realizacji: Fork Repository and Build Docs with Sphinx 9/21 Build Webpage with Four Spaces defined and linked 10/1 Move current tutorials into appropriate spaces and Build docs 10/10 Submit PR to github with proposed changes 11/1 Respond to comments/suggestions and revise PR ongoing with Outcome 2 Website revised 11/30
Rezultat 2: Poprawienie samouczków Data dostawy Data przeglądu samouczków z 21 września Dzielenie bieżącego samouczka w pokojach samouczków i Wyjaśnień 10/1 Zapis klasy 1: Tablice do odczytu i zapisu 10/10 Prześlij PR do github w celu rozdzielenia i wersji 10/20 Zapisz ocenę 2: Tablica PR pozycje PR 1/15 Ranking elementu PR 1/15 Ranking PR 1/15
Proponowane ułożenie wersji samouczka (może ulec zmianie w zależności od mentorów/społeczności):
Tablice odczytu/zapisu na aktualnej pustej stronie
Tworzenie tablic (np.zeros, np.ones, np.block itp.) Nie istnieje: nowi użytkownicy mogliby skorzystać z wyjaśnień i demonstracji typowych narzędzi do tworzenia i interakcji z tablicami.
Element-wise and linear algebra operations (+,-,*,/ and +,-@,linalg.solve) Does not exist: this is especially helpful for 1. Użytkownicy Matlaba i 2. Osoby stosujące algebrę liniową (uczenie maszynowe, regresja liniowa itp.)
Wynik 3. Selekcjonowane miejsce na instrukcje Termin realizacji Link zewnętrzny(wydanie/przykład)
Przygotuj przykład instrukcji (możliwa opcja: jak znaleźć naturalne częstotliwości strun gitary 10/20
Przygotuj szablon instrukcji dla nowych współtwórców 10/1 w trakcie realizacji Przygotuj szablon samouczka do przesłania do sprawdzenia i określ możliwe sposoby udziału
Współpracuj z innymi współtwórcami przy tworzeniu zeszytów z instrukcjami, aby zachęcić do udziału studentów UConn i innych członków społeczności 7/1 stan: praca-szansa została zatwierdzona, a aplikacje napływają
Oczekiwane znaczenie
Ta propozycja Google Summer of Docs pozwoli utworzyć dokumentację NumPy, uzupełnić brakujące samouczki na stronie internetowej i pozyskać współautorów dokumentacji. Jako profesor inżynierii mechanicznej planuję podzielić dokumentację w taki sposób, aby moi studenci mogli się po niej poruszać i łatwo znajdować samouczki wprowadzające oraz praktyczne instrukcje. Dokumentacja podzielona na części: samouczek, instrukcje, materiały referencyjne i wyjaśnienia zapewni potencjalnym autorom uporządkowane przykłady, które pomogą im w tworzeniu nowych zasobów. Proponowana dokumentacja umożliwia dzielenie się wiedzą przez edukację i komunikację zarówno nowym, jak i doświadczonym użytkownikom. Proponowany dokument z poradami dla studentów Uniwersytetu Connecticut pozwoli wdrożyć w praktyce tę ideę edukacji i komunikacji. Chcemy, aby wszyscy użytkownicy mogli eksperymentować, uczyć się i dołączać do społeczności NumPy.
Pliki referencyjne
- Strona NumPy.org została udostępniona w lipcu 2020 r.
- Repozytorium NumPy na GitHubie.
- system dokumentacji. Strona Divio.com dostępna w lipcu 2020 r.
- Dewey, John. Demokracja i edukacja. Project Gutenberg, sierpień 2015 r.
- Dewey, John. Misja Certainty George Allen And Unwin Limited. 06/2005