Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- NumPy
- Pisarz techniczny:
- cooperrc
- Nazwa projektu:
- Dokumentacja NumPy do edukacji społeczności
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Wstęp
NumPy udostępnia proste i szybkie przetwarzanie w tablicy w ramach bezpłatnej biblioteki oprogramowania typu open source. Jest to podstawowy pakiet stosu SciPy do obliczeń naukowych [1]. Ponad 370 tys. projektów wykorzystuje efektywne obliczenia tablicowe [2]. Użytkownikom NumPy pojawia się nowa witryna z aplikacjami i studiami przypadków [1]. Gdy nowy użytkownik znajdzie stronę z dokumentacją, zobaczy wiele linków „Zacznij tutaj” i wstępnych samouczków, które mogą być przytłaczające dla początkujących, takie jak NumPy Basics czy zamiana bajtów. Zacząłem używać NumPy 10 lat temu na studiach. Składałam posty na blogu, notatki z wykładów i odpowiedzi ze StackExchange, aby uniknąć zagłębiania się w dokumentację NumPy. Obecnie istnieje ponad 360 tys. wątków StackExchange dotyczących NumPy. Sądzę, że inni użytkownicy osiągnęli podobne sukcesy w NumPy. Elementy składowe narzędzi edukacyjnych to komunikacja i społeczność [4]. Dokumentacja powinna pozwalać na stworzenie społeczności, która będzie odzwierciedlała cele projektu. Dokumentacja powinna być spójna i zrozumiała dla nowego użytkownika. Samouczki powinny zawierać proste instrukcje dla nowych użytkowników i zapewnić im komfort korzystania z biblioteki [3]. Dokumentacja powinna powitać nowego użytkownika w społeczności NumPy. Struktura, tempo i autorzy dokumentacji muszą stworzyć miejsce, w którym użytkownicy będą chętniej odkrywać świat i komunikować się z innymi. Ta propozycja ma na celu uporządkowanie i uzupełnienie luk w bieżącej dokumentacji NumPy, zapewniając wiedzę nowym użytkownikom i powitanie ich w społeczności.
Wiedza, którą przekazują użytkownicy, zdobywa się podczas testowania i eksperymentowania [4,5]. Wiedza zależy od metody testowania i oceny. Treści, które jasno określają cele i zastosowania instrukcji, pozwalają użytkownikom testować i oceniać nowe pomysły i metody. Społeczność może zbudować bazę wiedzy, wzbogacając swoje umiejętności, fakty i aplikacje. Ilość miejsca w formie porad jest podwójna. Po pierwsze, nowi i doświadczeni użytkownicy mają jasno określone cele do testowania i tworzenia eksperymentów. Po drugie, potencjalni współtwórcy dokumentacji mają miejsce, w którym mogą przedstawić swoje cele, metody i rozwiązania. Wypełniliśmy tę instrukcję, co jest teraz konieczne, aby dokumentacja NumPy była bardziej dostępna dla nowych użytkowników i możliwych współtwórców. Bieżąca wiedza
John Dewey stwierdził, że podstawą uczenia się jest autentyczne doświadczenie [4]. Społeczność NumPy zawiera mnóstwo autentycznych wrażeń, które można udostępniać innym użytkownikom. Edukacja opiera się na społeczności i komunikacji. Uporządkowana strona z dokumentacją ułatwia nowym użytkownikom korzystanie z NumPy. Tworzy on też uporządkowany szablon, który umożliwia potencjalnym współtwórcom przekazywanie informacji o doświadczeniach w NumPy.
Dokumentacja oprogramowania obejmuje 4 ogólnie uporządkowane przestrzenie: samouczki, instrukcje, wyjaśnienia i materiały referencyjne. W dokumentacji NumPy znajduje się kilka dokumentów, które zawierają zarówno wyjaśnienia, jak i poradniki dotyczące kosmosu. Samouczki powinny koncentrować się na edukacji użytkownika i przedstawiać pomysły w sposób łatwy do powtórzenia. Poradniki oferują więcej procedur nastawionych na cel, które użytkownicy mogą zastosować w rzeczywistych zastosowaniach. W obszarze z objaśnieniem znajdują się szczegółowe informacje w sekcjach dokumentów w każdej funkcji. Tematy w bieżącym samouczku i instrukcjach nie są wyraźnie oddzielone, a czasem pojawiają się w obszarach z objaśnieniami i materiałami referencyjnymi. W aplikacji „Numpy dla użytkowników Matlab” znajdziesz świetny samouczek dla początkujących, a w aplikacji „Numpy dla użytkowników Matlab” znajdziesz przydatne wskazówki dotyczące tworzenia kodu Numpy. Precyzyjne rozdzielanie tych 4 obszarów sprawia, że dokumentacja jest bardziej zrozumiała.
Luki w bazie wiedzy/niewykorzystane potrzeby
Obecna dokumentacja obejmuje wiele niezbędnych tematów, ale nie ma wyraźnego rozróżnienia między samouczkami, instrukcjami, objaśnieniami i materiałami referencyjnymi. Sprawi to, że potencjalni współtwórcy mogą czuć się wprowadzeni w błąd. Nowi użytkownicy mogą być przytłoczeni opisami oraz materiałami referencyjnymi dostępnymi w samouczku, a potencjalni współtwórcy będą mieli trudności z dodaniem informacji. Proponuję bardziej przystępny układ dla nowych użytkowników i możliwych współtwórców dokumentacji, zapewniający logiczny przepływ w dokumentacji i zarządzanie żądaniami pull do dokumentów instruktażowych przesyłanych przez użytkowników. Moim celem długoterminowym jest zbudowanie społeczności dokumentacji, aby uczenie się z nich było oparte na przekazywaniu wiedzy i przekazywaniu wiedzy. Ten model dokumentacji będzie opierać się na rzeczywistym kształceniu nowych uczestników i potencjalnych współtwórców.
Uzasadnienie
Oferta „Lato Dokumentów Google” jest ważna dla moich celów pedagogicznych i zawodowych. Używam NumPy i SciPy we wszystkich kursach, z których korzystam. Moi uczniowie mają problem z poruszaniem się po bieżącej dokumentacji. Chcę wykorzystać swoje doświadczenie w nauczaniu specjalistów od specjalności IT, jak kodowanie, aby pomóc w porządkowaniu, edytowaniu i wypełnianiu luk w obecnych samouczkach. Następnie mogę wykorzystać dokumentację jako podręcznik i materiały referencyjne do moich kursów. Opracowałam dziesiątki samouczków, ćwiczeń i przykładów, używając Pythona i
Określone cele
Propozycja kampanii „Lato Dokumentów Google” ma 3 cele: 1. uporządkować aktualną dokumentację, 2. Edytuj aktualne samouczki (Przewodnik dla początkujących, tworzenie tablicy, indeksowanie, algebra liniowa i NumPy dla Matlab), aby przenieść informacje referencyjne do obszaru objaśniania. 3. Opracowywanie przez uczniów materiałów instruktażowych. Każdy cel ma oczekiwany wynik.
Te 3 cele mają sprawić, że dokumentacja będzie bardziej przydatna dla nowych użytkowników i ułatwi uporządkowanie treści potencjalnym współtwórcom. Ma to też pomóc w realizacji długoterminowego celu, jakim jest dalsze budowanie społeczności dokumentacji NumPy. Oczekiwane wyniki
Spodziewam się 3 oczekiwanych rezultatów: 1. poprawiona strona internetowa z dokumentacją, która wyraźnie rozdziela 4 poniższe sekcje: samouczki, instrukcje, wyjaśnienia i odwołania; 2. nowe samouczki dotyczące odczytu i zapisu tablic, tworzenia tablic (np.zeros, np.ones, np.block itp.) oraz działań opartych na elementach a algebra liniowa w NumPy oraz 3. specjalnie dobrane instrukcje.
Te oczekiwane rezultaty ułatwią nowym użytkownikom przeglądanie dokumentów, zapewni potencjalnym współtwórcom konkretne style i formaty, skróci i zrozumiałe samouczki, przenieś wyjaśnienia do osobnej sekcji, a nowi współtwórcy dokumentacji będą mogli wprowadzać niewielkie przypadki użycia do tej sekcji z instrukcjami bez konieczności tworzenia całej dokumentacji dotyczącej Sphinxa. Chcemy dalej rozwijać naszą społeczność edukacyjną.
Nowi współtwórcy dokumentacji mogą przekazywać drobne przypadki użycia milionom użytkowników bez konieczności tworzenia całej dokumentacji dotyczącej Sphinxa. Chcemy dalej rozwijać naszą społeczność edukacyjną. Dokumentacja będzie naśladować obecną dokumentację typu open source, np. Matplotlib czy Divio. Nowi użytkownicy i potencjalni współtwórcy będą mogli łatwiej nauczyć się stosowania NumPy w swoich dziedzinach i oprogramowaniu.
Czas realizacji projektu to 14–30 września. Pierwszym krokiem jest opracowanie dokumentacji i osobnych treści obecnych w naszych samouczkach – tutoriale, instrukcje i objaśnienia. Będzie to możliwe w ciągu pierwszych 5 tygodni trwania projektu w ramach Rezultatów 1 i 2 – korekty witryny i samouczków. Proponowana organizacja dokumentacji jest widoczna w proponowanej dokumentacji poniżej.
Proponowana dokumentacja:
i.Tutorials:
- Podstawowe informacje dla początkujących (usunąć instalację, czy pandy można importować/eksportować za pomocą pliku numpy.loadtxt?)
- link do „Co to jest numpy?”
- link do podstawowych instrukcji instalacji
- Krótki samouczek (przeznaczony do dalszego korzystania z samouczka Python)
- Praca z tablicami NumPy
- tworzenie tablicy (np.zeros, np.ones, np.block itp.) (zapis: średni-niski priorytet)
- operacje związane z elementami (+,-,*,/) i operacje na algebrie liniowej (+,-,@, linalg.solve) (priorytet zapis:med)
- Odczyt i zapis danych przy użyciu Numpy (zapis: wysoki priorytet)
- Indeksowanie
ii. Instrukcje:
- algebra liniowa w tablicach n-wymiarowych (warto zmienić nagłówki i opisy, a może zmienić tytuł na „Przetwarzanie obrazu za pomocą algebry liniowej Numpy'ego”)
- link do materiałów instruktażowych numpy-tutorials (ciągła praca)
iii. Wyjaśnienie:
- Typy danych
- I/O z Numpy
- Indeksowanie
- Transmisja
- Zamiana bajtów
- Tablice uporządkowane
- Zapisywanie kontenerów tablicy niestandardowej
- podklasyfikacja ndarraya
- Różne
iv. Obszar referencyjny:
- Glosariusz
- Dokumentacja API Numpy
- Numpy dla użytkowników Matlab (tabela równoważności to świetna tabela referencyjna, ale dyskusja na temat tablic i macierzy jest rozpraszająca i wydaje się wycofana)
Po zakończeniu tego sezonu Dokumentów Google proponuję następujące rezultaty:
- poprawiona strona internetowa z dokumentacją, która wyraźnie dzieli 4 poniższe sekcje: Samouczki, Instrukcje, Wyjaśnienie i Materiały referencyjne.
- Nowe samouczki dotyczące tworzenia tablic (np.zeros, np.ones, np.block itp.), operacji związanych z elementami (+,-,*,/) i algebry liniowej (+,-,@, linalg.solve) oraz odczytu i zapisu danych za pomocą Numpy (wysoki priorytet)
- Zaproponowano dokumenty z instrukcjami, aby zwiększyć wkład użytkowników i pomóc w osiągnięciu celów społeczności w zakresie nauczania i zdobywania wiedzy
Każdy wynik obejmuje szereg kroków opisanych poniżej w tabelach dla Wyników 1–3. Podczas gdy proponowana dokumentacja jest przesyłana do sprawdzenia, samouczek o wysokim priorytecie „Tablice do odczytu i zapisu” zostanie przygotowany do przesłania jako żądanie pull w ramach wyniku 2. W ramach przeglądu poprawionej witryny i zaktualizowanego samouczka „Tablice do odczytu i zapisu” zacznę pisać samouczek dotyczący tworzenia tablic przy użyciu funkcji NumPy, takich jak np.ones, np.zeros, np.diag. Pozostały czas zostanie wykorzystany na reagowanie na problemy związane z żądaniami wyciągnięcia i rozpoczęcie pisania samouczka „Ranking 3”: operacje na algebrie elementów i algebry liniowej w Pythonie.
W ramach trzeciego efektu jest doradzanie studentom z Uniwersytetu w Connecticut w zakresie tworzenia dokumentacji w repozytorium numpy-tutorials. Przesłane samouczki lub dokumenty instruktażowe będą notatnikami Jupyter, które używają NumPy do rozwiązywania problemów inżynieryjnych. Wykorzystam niektóre notatki/przykłady z kursu, aby przesłać przykładowy notatnik. Podczas tworzenia szablonu i schematu ramki będę radzić uczniom, aby korzystali z układu i struktury elementów. W ten sposób uczniowie mogą zaprezentować swoje pomysły i rozwiązania szerszemu gronu odbiorców. To świetna okazja dla uczniów, by zaangażować się w społeczność NumPy i nauczyć się.
Wynik 1: Popraw termin realizacji projektu w witrynie Rozbuduj Repozytorium i Tworzenie dokumentów we współpracy ze sfinksem 21.09 Utwórz stronę internetową ze zdefiniowanymi i połączonymi pokojami 10.10 Przenieś bieżące samouczki do odpowiednich obszarów i Dokumentacja tworzenia 10/10 Prześlij PR do github z proponowanymi zmianami 11/1 Odpowiadaj na komentarze/sugestie oraz poprawiaj wyniki 2
Wynik 2: Skrócenie samouczków Data dostawy Zapoznanie się z samouczkami i rankingiem wersji 10/21 Rozdziel bieżący samouczek na przestrzenie samouczka i objaśnienia 10/1 Zapis rankingu 1: tablice odczytu/zapisu 10/10 Prześlij operacje PR do github w celu rozdzielenia i poprawka 10/20 Zapisanie pozycji 2: tablica 1 Zapis PR1
Proponowany ranking zmian w samouczku (może się zmienić w zależności od mentorów/społeczności):
Pusta strona do odczytu/zapisu tablic
Tworzenie tablicy (np.zeros, np.ones, np.block itp.) Nie istnieje: ułatwi nowym użytkownikom wyjaśnienie i zademonstrowanie typowych narzędzi do tworzenia tablic i interakcji.
Operacje na algebrach liniowych i dotyczące elementów (+,-,*,/ i +,-@,linalg.solve) nie istnieją: ta funkcja jest szczególnie przydatna w przypadku 1. Użytkownicy Matlab. 2. Osoby stosujące algebrę liniową (systemy uczące się, regresja liniowa itp.)
Wynik 3: Wyselekcjonowany poradnikowy link zewnętrzny(problem/przykład)
Tworzenie przykładu instrukcji (kandydat: jak znaleźć naturalne częstotliwości strun gitarowych 20/10
Opracowanie szablonu instrukcji dla nowych współtwórców 10/1 w toku Samouczek PR i umieszczanie w ramkach możliwych publikacji
Praca z innymi uczestnikami do tworzenia listy zatwierdzonych członków społeczności i tworzenia notatników U
Oczekiwana istotność
W ramach tej propozycji Google Summer of Dokumentów opracujemy dokumentację NumPy , uzupełnimy brakujące samouczki w witrynie i pozyskamy współautorów. Jako profesor inżynierii mechanicznej planuję podzielić dokumentację w taki sposób, aby moi uczniowie mogli przeglądać dokumenty i łatwo znajdować samouczki wprowadzające w porównaniu z praktycznymi poradnikami. Podzielona na segmenty dokumentacja (samouczek, instrukcje, materiały referencyjne i wyjaśnienie) zawiera uporządkowane przykłady tworzenia nowych zasobów potencjalnym współtwórcom. Proponowana dokumentacja nadaje się do przedstawienia nowym i doświadczonym użytkownikom w formie edukowania i komunikacji. Proponowany dokument instruktażowy, w którym studenci z Uniwersytetu Connecticut wdrożyli w praktyce. Chcemy, aby wszyscy użytkownicy mieli miejsce do eksperymentowania, nauki i dołączania do społeczności NumPy.
Odniesienia
- Dostęp do witryny NumPy.org z 7 lipca 2020 r.
- Repozytorium NumPy na GitHubie.
- System dokumentacji. Dostęp z Divio.com do 07.2020 r.
- Dewey, John. Demokracja i edukacja. Projekt Gutenberg, sierpień 2015 r.
- Dewey, John. Quest for Certainty George Allen i Unwin Limited. 06/2005.