Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.
Ringkasan proyek
- Organisasi open source:
- NumPy
- Penulis teknis:
- cooperrc
- Nama proyek:
- Dokumentasi Angka untuk Pendidikan Komunitas
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
Pengantar
NumPy menghadirkan komputasi berbasis array yang bersih dan cepat dalam koleksi software open source gratis. Ini adalah paket fundamental dalam stack SciPy untuk komputasi ilmiah [1]. Lebih dari 370 ribu proyek digunakan untuk komputasi array yang efisien [2]. Pengguna NumPy akan disambut oleh situs web baru dengan aplikasi dan studi kasus [1]. Ketika pengguna baru menemukan halaman dokumentasi, mereka akan melihat beberapa link “Mulai Di Sini” dan tutorial pengantar yang mungkin membingungkan bagi pemula, seperti NumPy Basics/byte-swapping. Saya mulai menggunakan NumPy sepuluh tahun yang lalu di sekolah pascasarjana. Saya mengumpulkan postingan blog, catatan kuliah, dan jawaban StackExchange untuk menghindari membaca dokumentasi NumPy. Saat ini ada lebih dari 360 ribu percakapan StackExchange yang berhubungan dengan NumPy. Saya membayangkan pengguna lain memiliki rute yang serupa untuk meraih kesuksesan di NumPy. Komponen pendidikan adalah komunikasi dan komunitas [4]. Dokumentasi perlu membentuk komunitas yang mencerminkan tujuan yang diinginkan dari proyek. Dokumentasi harus konsisten dan merupakan panduan yang jelas untuk pengguna baru. Tutorial harus memberikan langkah-langkah yang mudah diikuti pengguna baru dan membangun kenyamanan dengan library [3]. Dokumentasi harus menyambut pengguna baru ke komunitas NumPy. Struktur, kecepatan, dan penulis dokumentasi semuanya perlu menciptakan tempat yang menyambut eksplorasi dan komunikasi. Proposal ini akan menyusun dan mengisi kekurangan dalam dokumentasi NumPy saat ini sehingga pengguna baru memahami dan disambut dengan baik di komunitas.
Pengetahuan yang dikomunikasikan pengguna diperoleh melalui pengujian dan eksperimen [4,5]. Pengetahuan bergantung pada metode pengujian dan evaluasi. Konten yang memberikan tujuan dan penerapan yang jelas dalam panduan memungkinkan pengguna untuk menguji dan mengevaluasi ide dan metode baru. Komunitas dapat membangun basis pengetahuan untuk meningkatkan keterampilan, fakta, dan penerapan. Ruang {i>how-to<i} memberikan manfaat dua kali lipat. Pertama, pengguna baru dan berpengalaman memiliki serangkaian tujuan yang jelas untuk menguji dan membuat eksperimen. Kedua, calon kontributor dokumentasi memiliki ruang untuk mengkomunikasikan tujuan, metode, dan solusi mereka. Ruang "petunjuk" mengisi kebutuhan mendesak untuk membuat dokumentasi NumPy lebih mudah diakses oleh pengguna baru dan calon kontributor. Pengetahuan Saat Ini
John Dewey mengatakan bahwa dasar dari pembelajaran adalah pengalaman yang nyata [4]. Komunitas NumPy memiliki pengalaman asli yang luar biasa dan dapat dibagikan kepada pengguna lain. Pendidikan dibangun berdasarkan komunitas dan komunikasi. Halaman dokumentasi yang tertata rapi menjelaskan cara bagi pengguna baru untuk menggunakan NumPy. Ini juga membuat template terstruktur bagi calon kontributor untuk menyampaikan pengalaman di NumPy.
Ada empat ruang yang dikelompokkan secara luas untuk dokumentasi perangkat lunak [3]: ruang tutorial, ruang petunjuk, ruang penjelasan, dan ruang referensi. Dokumentasi NumPy memiliki sejumlah dokumen di ruang tutorial yang menggabungkan penjelasan dan konten petunjuk untuk memberi ruang ke dalam tutorial. Ruang tutorial harus berfokus pada edukasi pengguna dan menggunakan langkah-langkah yang mudah diulang untuk mengomunikasikan ide. Ruang {i>how-to<i} menyediakan lebih banyak prosedur yang berorientasi pada tujuan yang dapat diterapkan pengguna dalam aplikasi dunia nyata. Ruang penjelasan menyediakan informasi terperinci mengenai {i>doc-string<i} di setiap fungsi. Ruang tutorial dan petunjuk saat ini tidak digambarkan dengan jelas dan terkadang masuk ke dalam ruang penjelasan dan referensi. Ada tutorial yang sangat bagus untuk "Absolute Beginner" dan ada referensi bagus bagi pengguna Matlab untuk membuat kode NumPy di "Numpy untuk pengguna Matlab". Menggambarkan keempat spasi ini dengan jelas membuat dokumentasi lebih jelas.
Kesenjangan dalam Basis Pengetahuan/Kebutuhan yang Belum Terpenuhi
Dokumentasi saat ini mencakup banyak topik yang diperlukan, tetapi tidak memiliki perbedaan yang jelas antara ruang tutorial, petunjuk, penjelasan, dan referensi. Hal ini menyebabkan kebingungan bagi calon kontributor. Pengguna baru dapat kewalahan dengan penjelasan dan materi referensi di bagian tutorial, dan calon kontributor dihadapkan pada rintangan untuk berkontribusi. Saya mengusulkan tata letak yang lebih mudah diakses untuk pendatang baru dan kontributor dokumentasi yang mungkin dengan alur logis dalam dokumentasi dan mengelola permintaan pull untuk dokumen petunjuk yang dikontribusikan oleh pengguna oleh kontributor baru. Tujuan jangka panjang saya adalah membangun komunitas dokumentasi sehingga belajar dari dokumentasi adalah pengalaman mendidik dan mengomunikasikan. Model dokumentasi ini akan memberikan dasar pendidikan pada pengalaman aktual bagi pendatang baru dan calon kontributor.
Argumentasi
Proposal Google Summer of Docs ini penting untuk tujuan pedagogis dan karier saya. Saya menggunakan NumPy dan SciPy dalam semua kursus saya. Dokumentasi saat ini sulit dijelajahi oleh siswa saya. Saya ingin menggunakan pengalaman saya mengajar jurusan non-CS tentang cara membuat kode untuk membantu mengatur, mengedit, dan mengisi kekosongan dalam tutorial saat ini. Kemudian, saya dapat menggunakan dokumentasi tersebut sebagai buku teks dan materi referensi untuk kursus saya. Saya telah membuat puluhan tutorial, latihan, dan contoh menggunakan Python dan
Tujuan Spesifik
Saya mempunyai tiga tujuan khusus untuk proposal Google Summer of Docs ini: 1. Menyusun dokumentasi terbaru, 2. Edit tutorial saat ini (Panduan Pemula, Pembuatan Array, Pengindeksan, Aljabar Linier, dan NumPy untuk Matlab) untuk memindahkan informasi referensi ke Ruang Penjelasan, dan 3. Membuat materi petunjuk dengan siswa. Setiap tujuan spesifik memiliki hasil yang diharapkan untuk proposal.
Ketiga tujuan spesifik ini dimaksudkan untuk membuat dokumentasi lebih ramah bagi pengguna baru dan memberikan struktur bagi calon kontributor. Tujuan ini juga membantu melanjutkan tujuan jangka panjang untuk terus mengembangkan komunitas dokumentasi NumPy. Hasil yang Diharapkan
Saya memiliki tiga hasil yang diharapkan: 1. Halaman web dokumentasi yang direvisi yang dengan jelas memisahkan empat ruang: tutorial, petunjuk, penjelasan, dan referensi, 2. tutorial baru untuk: membaca dan menulis array, pembuatan array (np.zeros, np.ones, np.blok, dll.), dan operasi aljabar element-wise vs linear di NumPy, dan 3. panduan yang dikuratori ruang.
Hasil yang diharapkan ini akan membantu pengguna baru mengembangkan dokumen, memberikan gaya dan format yang jelas kepada kontributor dokumentasi yang potensial, membuat tutorial yang ada saat ini menjadi lebih pendek dan lebih mudah diikuti, memindahkan penjelasan ke bagian terpisah, dan kontributor dokumentasi baru akan dapat berkontribusi dalam kasus penggunaan kecil ke bagian petunjuk tanpa harus membuat seluruh dokumentasi Sphinx. Kami ingin terus membangun komunitas belajar-mengajar.
Kontributor dokumentasi baru dapat menyumbangkan kasus penggunaan kecil kepada jutaan pengguna tanpa harus membangun seluruh dokumentasi Sphinx. Kami ingin terus membangun komunitas belajar-mengajar. Dokumentasi yang diusulkan ini akan meniru dokumentasi open source saat ini seperti Matplotlib, Divio, dll. Pengguna baru dan calon kontributor akan lebih mudah belajar menerapkan NumPy di bidang dan software mereka.
Rentang waktu untuk proyek ini adalah 9/14-11/30. Langkah pertama adalah membuat dokumentasi dan memisahkan konten dalam tutorial saat ini menjadi konten Tutorial, Petunjuk, dan Penjelasan. Hal ini akan dilakukan dalam lima minggu pertama proyek sebagai bagian dari Hasil 1 dan 2 revisi situs web dan tutorial. Organisasi Dokumentasi yang diusulkan ditampilkan dalam Dokumentasi yang Diusulkan di bawah ini.
Dokumentasi yang Diusulkan:
i.Tutorials:
- Dasar-dasar absolut untuk pemula (menghapus penginstalan, dapatkah impor/ekspor pandas diganti dengan numpy.loadtxt?)
- tautan ke “Apa itu numpy”
- tautan ke petunjuk penginstalan dasar di sini
- Tutorial Panduan Memulai (dimaksudkan untuk menindaklanjuti tutorial Python )
- Menangani array NumPy
- pembuatan array (np.zeros, np.ones, np.block, dll.) (tulis: prioritas sedang-rendah)
- operasi element-wise (+,-,*,/) dan operasi aljabar linear (+,-,@, linalg.resolve) (prioritas tulis:med)
- Membaca dan menulis data menggunakan Numpy (tulis: prioritas tinggi)
- Pengindeksan
ii. Petunjuk:
- Aljabar Linear pada array n-dimensi (akan senang mengedit judul dan deskripsi dan mungkin mengubah judul menjadi "Pemrosesan gambar dengan aljabar linear Numpy")
- tautan ke konten petunjuk numpy-tutorial (kerja berkelanjutan)
iii. Penjelasan:
- Jenis data
- I/O dengan Numpy
- Pengindeksan
- Menyiarkan
- {i>Byte-swapping<i}
- Array terstruktur
- Menulis penampung array kustom
- membuat subclass ndarray
- Lain-lain
iv. Ruang Referensi:
- Glosarium
- Referensi Numpy API
- Numpy untuk pengguna Matlab (tabel kesetaraan adalah tabel referensi yang bagus, tetapi diskusi array/matriks mengganggu dan tampaknya tidak digunakan lagi)
Setelah menyelesaikan Google Season Dokumen ini, kami mengusulkan hasil berikut:
- Laman web Dokumentasi hasil revisi yang dengan jelas memisahkan keempat bagian: Tutorial, Petunjuk, Penjelasan, dan Referensi
- Tutorial Baru untuk: pembuatan array (np.zeros, np.ones, np.block, dll.), operasi element-wise (+,-,*,/) dan operasi aljabar linear (+,-,@, linalg.resolve), dan Membaca dan menulis data menggunakan Numpy (prioritas tinggi)
- Dokumen petunjuk yang disarankan untuk meningkatkan kontribusi pengguna dan membantu mencapai tujuan komunitas dalam pengajaran dan pembelajaran lebih lanjut
Setiap hasil memiliki sejumlah langkah yang diuraikan di bawah ini dalam tabel untuk Hasil 1-3. Sementara Dokumentasi yang Diusulkan dikirimkan untuk ditinjau, tutorial “{i>Read/write array<i}” prioritas tinggi akan ditulis untuk diserahkan sebagai permintaan pull sebagai bagian dari Hasil 2. Selama peninjauan situs yang direvisi dan tutorial "Read/Write array" yang diperbarui, saya akan mulai menulis tutorial untuk membuat array menggunakan fungsi NumPy misalnya np.ones, np.zeros, np.diag. Sisa waktu akan digunakan untuk merespons masalah permintaan pull dan mulai menulis tutorial peringkat 3: Operasi aljabar linear dan berbasis elemen di Python.
Hasil ketiga adalah menyarankan mahasiswa di University of Connecticut untuk membuat dokumentasi di repositori numpy-tutorials. Tutorial atau dokumen petunjuk yang dikirimkan adalah notebook Jupyter yang menggunakan NumPy untuk menyelesaikan masalah teknik. Saya akan menggunakan beberapa catatan/contoh kursus untuk mengirimkan contoh buku catatan. Saya akan menyarankan siswa untuk mengikuti tata letak dan struktur saat kita membuat template dan skema framing. Hasil ini menghadirkan pengalaman yang nyata bagi siswa untuk mengomunikasikan konsep dan solusi kepada audiens yang lebih luas. Ini adalah kesempatan bagus bagi siswa untuk terlibat dengan komunitas NumPy dan belajar.
Hasil 1: Merevisi Tanggal Pengiriman situs Fork Repository dan Build Docs dengan Sphinx 9/21 Membuat Halaman Web dengan Empat Ruang yang ditetapkan dan ditautkan 10/1 Pindahkan tutorial saat ini ke ruang yang sesuai dan Dokumen build 10/10 Mengirim PR ke github dengan perubahan yang diusulkan 11/1 Merespons komentar/saran dan merevisi Laporan PR yang sedang berlangsung dengan Hasil 1
Hasil 2: Merevisi tutorial Hasil tutorial Tinjau peringkat revisi tutorial 21/9 Pisahkan konten tutorial saat ini ke dalam ruang Tutorial dan Penjelasan 10/1 Tulis peringkat 1: Baca/Tulis array 10/10 Kirim PR ke github untuk pemisahan dan revisi 10/20 Tulis peringkat 2: Operasi Pembuatan Array PR-Tulis Peringkat 11/15
Usulan peringkat revisi tutorial (dapat berubah sesuai dengan mentor/komunitas):
Halaman array Read/Write saat ini kosong
Pembuatan array (np.zeros, np.ones, np.block, dll.) Tidak ada: akan membantu pengguna baru untuk menjelaskan dan menunjukkan alat pembuatan/interaksi array umum
Operasi aljabar linear dan {i>element<i}-{i>wise<i} (+,-,*,/ dan +,-@,linalg.resolve) Tidak ada: ini sangat membantu untuk 1. Pengguna Matlab dan 2. Orang yang menggunakan aljabar linear (machine learning, regresi linear, dll.)
Hasil 3: Bagian Petunjuk yang Dikurasi Tanggal Hasil Penyampaian Link Eksternal(masalah/contoh)
Contoh Build Petunjuk (kandidat: Cara menemukan frekuensi senar gitar yang alami 10/20
Membuat template Petunjuk untuk kontributor baru 10/1 sedang dalam proses Template tutorial PR & Membingkai kontribusi yang memungkinkan
Bekerja dengan kontributor lain untuk membuat notebook Petunjuk yang merekrut siswa UConn7 dan anggota komunitas lain yang disetujui:
Signifikansi yang Diharapkan
Proposal Google Summer of Docs ini akan membuat dokumentasi NumPy , mengisi tutorial yang belum lengkap dari situs web, dan mendapatkan kontributor dokumentasi. Sebagai Profesor di bidang Teknik Mesin, saya berencana untuk menyegmentasikan dokumentasi sedemikian rupa sehingga siswa saya dapat menavigasi dokumen dan dengan mudah menemukan tutorial pengantar vs panduan cara kerja langsung. Dokumentasi yang disegmentasikan: tutorial, petunjuk, referensi, dan penjelasan akan memberikan contoh terstruktur kepada calon kontributor untuk membuat referensi baru. Dokumentasi yang diusulkan ini dapat membantu pengguna baru dan berpengalaman dalam memberikan dan menerima melalui pendidikan dan komunikasi. Dokumen petunjuk yang kami usulkan kepada mahasiswa University of Connecticut akan mempraktikkan ide edukatif dan komunikasi ini. Kami ingin semua pengguna dapat menemukan ruang untuk bereksperimen, belajar, dan bergabung dengan komunitas NumPy.
Referensi
- Situs NumPy.org diakses 07/2020.
- Repositori GitHub NumPy.
- Sistem Dokumentasi. Divio.com diakses 07/2020.
- Dewey, John. Demokrasi dan Pendidikan. Proyek Gutenberg, Agustus 2015.
- Dewey, John. Misi untuk Kepastian George Allen Dan Unwin Limited. 06/2005.